Repository: EDDYCJY/blog
Branch: master
Commit: 5d1b9c17c374
Files: 260
Total size: 1.1 MB

Directory structure:
gitextract_hs1r1ie2/

├── .gitignore
├── README.md
├── archetypes/
│   ├── default.md
│   └── posts.md
├── config.toml
├── content/
│   ├── about.md
│   ├── go-categories.md
│   ├── k8s-categories.md
│   ├── posts/
│   │   ├── 2020-summary.md
│   │   ├── 2020-top100.md
│   │   ├── 2021-ecug.md
│   │   ├── 2021giac.md
│   │   ├── go/
│   │   │   ├── 117-build.md
│   │   │   ├── 117-errorstack.md
│   │   │   ├── 117-generics.md
│   │   │   ├── 117-module-pruning-lazy.md
│   │   │   ├── 117-performance.md
│   │   │   ├── 118-build-info.md
│   │   │   ├── 118-build.md
│   │   │   ├── 118-constraints.md
│   │   │   ├── 118-cut.md
│   │   │   ├── 118-leader-generics.md
│   │   │   ├── 118-module.md
│   │   │   ├── 4errors.md
│   │   │   ├── again-mutex.md
│   │   │   ├── annotation.md
│   │   │   ├── any.md
│   │   │   ├── class-extends.md
│   │   │   ├── crawler/
│   │   │   │   ├── 2018-03-21-douban-top250.md
│   │   │   │   ├── 2018-04-01-cars.md
│   │   │   │   └── 2018-04-28-go2018.md
│   │   │   ├── defer/
│   │   │   │   └── 2019-05-27-defer.md
│   │   │   ├── delve.md
│   │   │   ├── empty-struct.md
│   │   │   ├── enum.md
│   │   │   ├── func-reload.md
│   │   │   ├── fuzzing.md
│   │   │   ├── gdb.md
│   │   │   ├── generics-apis.md
│   │   │   ├── generics-design.md
│   │   │   ├── generics-proposal.md
│   │   │   ├── gin/
│   │   │   │   ├── 2018-02-10-install.md
│   │   │   │   ├── 2018-02-11-api-01.md
│   │   │   │   ├── 2018-02-12-api-02.md
│   │   │   │   ├── 2018-02-13-api-03.md
│   │   │   │   ├── 2018-02-14-jwt.md
│   │   │   │   ├── 2018-02-15-log.md
│   │   │   │   ├── 2018-03-15-reload-http.md
│   │   │   │   ├── 2018-03-18-swagger.md
│   │   │   │   ├── 2018-03-24-golang-docker.md
│   │   │   │   ├── 2018-03-26-cgo.md
│   │   │   │   ├── 2018-04-15-gorm-callback.md
│   │   │   │   ├── 2018-04-29-cron.md
│   │   │   │   ├── 2018-05-27-config-upload.md
│   │   │   │   ├── 2018-06-02-application-redis.md
│   │   │   │   ├── 2018-06-14-excel.md
│   │   │   │   ├── 2018-07-05-image.md
│   │   │   │   ├── 2018-07-07-font.md
│   │   │   │   ├── 2018-08-26-makefile.md
│   │   │   │   └── 2018-09-01-nginx.md
│   │   │   ├── gmp-why-p.md
│   │   │   ├── go-array-slice.md
│   │   │   ├── go-bootstrap.md
│   │   │   ├── go-bootstrap0.md
│   │   │   ├── go-concurrent-lock.md
│   │   │   ├── go-design.md
│   │   │   ├── go-empty-struct.md
│   │   │   ├── go-error2panic.md
│   │   │   ├── go-errors-boom.md
│   │   │   ├── go-golang.md
│   │   │   ├── go-map-access.md
│   │   │   ├── go-moduels/
│   │   │   │   ├── 2019-09-29-goproxy-cn.md
│   │   │   │   └── 2020-02-28-go-modules.md
│   │   │   ├── go-standards.md
│   │   │   ├── go-tips-defer.md
│   │   │   ├── go-tips-gmp-p.md
│   │   │   ├── go-tips-goroutineid.md
│   │   │   ├── go-tips-goroutineloop.md
│   │   │   ├── go-tips-goroutinenums.md
│   │   │   ├── go-tips-interface.md
│   │   │   ├── go-tips-lenstr.md
│   │   │   ├── go-tips-sturct.md
│   │   │   ├── go-tips-timer-memory.md
│   │   │   ├── go-typeparams-master.md
│   │   │   ├── go-why-path.md
│   │   │   ├── go1.16-1.md
│   │   │   ├── go1.16-2.md
│   │   │   ├── go1.16-3.md
│   │   │   ├── go1.16-mod.md
│   │   │   ├── go11.md
│   │   │   ├── go16-preview.md
│   │   │   ├── go2-errors.md
│   │   │   ├── gophercon2020-errors.md
│   │   │   ├── goroutine-27.md
│   │   │   ├── goroutine-errors.md
│   │   │   ├── goroutine-leak.md
│   │   │   ├── grpc/
│   │   │   │   ├── 2018-09-22-install.md
│   │   │   │   ├── 2018-09-23-client-and-server.md
│   │   │   │   ├── 2018-09-24-stream-client-server.md
│   │   │   │   ├── 2018-10-07-grpc-tls.md
│   │   │   │   ├── 2018-10-08-ca-tls.md
│   │   │   │   ├── 2018-10-10-interceptor.md
│   │   │   │   ├── 2018-10-12-grpc-http.md
│   │   │   │   ├── 2018-10-14-per-rpc-credentials.md
│   │   │   │   ├── 2018-10-16-deadlines.md
│   │   │   │   └── 2018-10-20-zipkin.md
│   │   │   ├── grpc-gateway/
│   │   │   │   ├── 2018-02-23-install.md
│   │   │   │   ├── 2018-02-27-hello-world.md
│   │   │   │   ├── 2018-03-04-swagger.md
│   │   │   │   └── 2019-06-22-grpc-gateway-tls.md
│   │   │   ├── import-cyc.md
│   │   │   ├── import-generics.md
│   │   │   ├── len.md
│   │   │   ├── map/
│   │   │   │   ├── 2019-03-05-map-access.md
│   │   │   │   ├── 2019-03-24-map-assign.md
│   │   │   │   └── 2019-04-07-why-map-no-order.md
│   │   │   ├── map-65.md
│   │   │   ├── map-con.md
│   │   │   ├── map-reset.md
│   │   │   ├── map-slice-concurrency.md
│   │   │   ├── memory-model.md
│   │   │   ├── news-slices-maps.md
│   │   │   ├── news115.md
│   │   │   ├── nil-func.md
│   │   │   ├── panic/
│   │   │   │   └── 2019-05-21-panic-and-recover.md
│   │   │   ├── pkg/
│   │   │   │   ├── 2018-09-28-log.md
│   │   │   │   ├── 2018-12-04-fmt.md
│   │   │   │   └── 2018-12-15-unsafe.md
│   │   │   ├── plugin.md
│   │   │   ├── real-context.md
│   │   │   ├── reflect.md
│   │   │   ├── runtimepark.md
│   │   │   ├── rust-php.md
│   │   │   ├── site-history.md
│   │   │   ├── slice/
│   │   │   │   ├── 2018-12-11-slice.md
│   │   │   │   └── 2019-01-06-why-slice-max.md
│   │   │   ├── slice-discuss.md
│   │   │   ├── slice-leak.md
│   │   │   ├── slice-string-header.md
│   │   │   ├── stop-goroutine.md
│   │   │   ├── struct-pointer.md
│   │   │   ├── switch-type.md
│   │   │   ├── sync-map.md
│   │   │   ├── talk/
│   │   │   │   ├── 2018-03-13-golang-relatively-path.md
│   │   │   │   ├── 2018-05-21-go-fake-useragent.md
│   │   │   │   ├── 2018-06-07-go-redis-protocol.md
│   │   │   │   ├── 2018-11-25-gomock.md
│   │   │   │   ├── 2018-12-26-go-memory-align.md
│   │   │   │   ├── 2019-01-20-control-goroutine.md
│   │   │   │   ├── 2019-02-17-for-loop-json-unmarshal.md
│   │   │   │   ├── 2019-03-31-go-ins.md
│   │   │   │   ├── 2019-05-20-stack-heap.md
│   │   │   │   ├── 2019-06-16-defer-loss.md
│   │   │   │   ├── 2019-06-29-talking-grpc.md
│   │   │   │   ├── 2019-09-07-go1.13-defer.md
│   │   │   │   └── 2019-09-24-why-vsz-large.md
│   │   │   ├── ternary-operator.md
│   │   │   ├── throw.md
│   │   │   ├── tools/
│   │   │   │   ├── 2018-09-15-go-tool-pprof.md
│   │   │   │   ├── 2019-07-12-go-tool-trace.md
│   │   │   │   ├── 2019-08-19-godebug-sched.md
│   │   │   │   └── 2019-09-02-godebug-gc.md
│   │   │   ├── type-after.md
│   │   │   ├── unsafe-pointer.md
│   │   │   ├── value-quote.md
│   │   │   ├── var.md
│   │   │   └── when-gc.md
│   │   ├── go-meetup1017.md
│   │   ├── go-programming-tour-book.md
│   │   ├── kubernetes/
│   │   │   ├── 2020-05-01-install.md
│   │   │   ├── 2020-05-03-deployment.md
│   │   │   └── 2020-05-10-api.md
│   │   ├── microservice/
│   │   │   ├── dismantle.md
│   │   │   ├── flowcontrol-circuitbreaker.md
│   │   │   ├── leaky-token-buckets.md
│   │   │   ├── linkage.md
│   │   │   ├── monitor-alarm.md
│   │   │   ├── standardization.md
│   │   │   ├── tests.md
│   │   │   └── tracing.md
│   │   ├── mq-nodus.md
│   │   ├── prometheus/
│   │   │   ├── 2020-05-16-metrics.md
│   │   │   ├── 2020-05-16-pull.md
│   │   │   └── 2020-05-16-startup.md
│   │   ├── reading/
│   │   │   ├── 2020-04-24-book.md
│   │   │   ├── documentary-of-go.md
│   │   │   ├── programmer-accom-base.md
│   │   │   ├── programmer-compile-link.md
│   │   │   └── programmer-linker.md
│   │   ├── reload-man.md
│   │   ├── where-is-proto.md
│   │   ├── why-container-memory-exceed.md
│   │   ├── why-container-memory-exceed2.md
│   │   └── why-mq.md
│   └── prometheus-categories.md
├── layouts/
│   ├── _default/
│   │   ├── baseof.html
│   │   ├── list.html
│   │   └── single.html
│   ├── index.html
│   ├── partials/
│   │   ├── analytics.html
│   │   ├── comments.html
│   │   ├── favicons.html
│   │   ├── footer.html
│   │   ├── header.html
│   │   ├── social-icons.html
│   │   ├── structured-data.html
│   │   └── svg.html
│   └── posts/
│       ├── rss.xml
│       └── single.html
├── resources/
│   └── _gen/
│       └── assets/
│           └── scss/
│               └── scss/
│                   ├── style.scss_c16d144eee185fbddd582cd5e25a4fae.content
│                   └── style.scss_c16d144eee185fbddd582cd5e25a4fae.json
├── static/
│   └── css/
│       └── styles.css
└── themes/
    └── hermit/
        ├── .editorconfig
        ├── .gitattributes
        ├── LICENSE
        ├── README.md
        ├── archetypes/
        │   ├── default.md
        │   └── posts.md
        ├── assets/
        │   ├── js/
        │   │   └── main.js
        │   └── scss/
        │       ├── _animate.scss
        │       ├── _normalize.scss
        │       ├── _predefined.scss
        │       ├── _syntax.scss
        │       └── style.scss
        ├── exampleSite/
        │   ├── config.toml
        │   └── content/
        │       ├── about-hugo.md
        │       └── posts/
        │           ├── creating-a-new-theme.md
        │           ├── goisforlovers.md
        │           ├── hugoisforlovers.md
        │           ├── migrate-from-jekyll.md
        │           ├── post-with-featured-image.md
        │           ├── the-figure-shortcode.md
        │           └── typography.md
        ├── i18n/
        │   ├── en.toml
        │   ├── it.toml
        │   └── zh-hans.toml
        ├── layouts/
        │   ├── 404.html
        │   ├── _default/
        │   │   ├── baseof.html
        │   │   ├── list.html
        │   │   └── single.html
        │   ├── index.html
        │   ├── partials/
        │   │   ├── analytics.html
        │   │   ├── favicons.html
        │   │   ├── footer.html
        │   │   ├── header.html
        │   │   ├── social-icons.html
        │   │   ├── structured-data.html
        │   │   └── svg.html
        │   ├── post/
        │   │   ├── rss.xml
        │   │   └── single.html
        │   └── posts/
        │       ├── rss.xml
        │       └── single.html
        ├── resources/
        │   └── _gen/
        │       └── assets/
        │           ├── js/
        │           │   └── js/
        │           │       ├── main.js_d11fe7b62c27961c87ecd0f2490357b9.content
        │           │       └── main.js_d11fe7b62c27961c87ecd0f2490357b9.json
        │           └── scss/
        │               └── scss/
        │                   ├── style.scss_c16d144eee185fbddd582cd5e25a4fae.content
        │                   └── style.scss_c16d144eee185fbddd582cd5e25a4fae.json
        ├── static/
        │   ├── browserconfig.xml
        │   ├── site.webmanifest
        │   └── utteranc.js
        └── theme.toml

================================================
FILE CONTENTS
================================================

================================================
FILE: .gitignore
================================================
.idea/
.DS_Store
_book/
node_modules/
public/


================================================
FILE: README.md
================================================
# 煎鱼的迷之博客

写写代码，喝喝茶，搞搞 Go，一起吧，这是我的项目地址：https://github.com/eddycjy/blog

## 在线阅读

- https://eddycjy.com/

## 我的公众号

所有文章和最新进度，请关注：

![image](https://image.eddycjy.com/7074be90379a121746146bc4229819f8.jpg)

## ？

如果有任何疑问或错误，欢迎在 issues 进行提问或给予修正意见

如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进 😀

## License

所有文章采用[知识共享署名-非商业性使用-相同方式共享 3.0 中国大陆许可协议](https://creativecommons.org/licenses/by-nc-sa/3.0/cn/)进行许可


================================================
FILE: archetypes/default.md
================================================
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
comments: false
images:
---



================================================
FILE: archetypes/posts.md
================================================
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
toc: false
images:
tags: 
  - untagged
---



================================================
FILE: config.toml
================================================
baseURL = "https://eddycjy.com"
languageCode = "zh-hans"
defaultContentLanguage = "en"
title = "煎鱼"
theme = "hermit"
# enableGitInfo = true
pygmentsCodefences  = true
pygmentsUseClasses  = true
# hasCJKLanguage = true  # If Chinese/Japanese/Korean is your main content language, enable this to make wordCount works right.
rssLimit = 10  # Maximum number of items in the RSS feed.
copyright = "This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License." # This message is only used by the RSS template.
enableEmoji = true  # Shorthand emojis in content files - https://gohugo.io/functions/emojify/
googleAnalytics = "UA-166045776-1"
# disqusShortname = "yourdiscussshortname"
summarylength = 30

[author]
  name = "煎鱼"

[blackfriday]
  # hrefTargetBlank = true
  # noreferrerLinks = true
  # nofollowLinks = true

[taxonomies]
  tag = "tags"
  # Categories are disabled by default.

[params]
  since = "2018"
  toc = true

  dateform        = "Jan 2, 2006"
  dateformShort   = "Jan 2"
  dateformNum     = "2006-01-02"
  dateformNumTime = "2006-01-02 15:04 -0700"

  # Metadata mostly used in document's head
  description = "煎鱼,博客,go,golang,源码分析,系列教程"
  # images = [""]
  themeColor = "#494f5c"

  mainSections = ["posts"]

  homeSubtitle = "Metrics, Tracing, Logging"
  footerCopyright = ' &#183; <a href="http://www.beian.miit.gov.cn/">粤ICP备19076352号</a>'
  # bgImg = ""  # Homepage background-image URL

  # Prefix of link to the git commit detail page. GitInfo must be enabled.
  gitUrl = "https://github.com/eddycjy/blog/commit/"

  # Toggling this option needs to rebuild SCSS, requires Hugo extended version
  justifyContent = false  # Set "text-align: justify" to `.content`.

  relatedPosts = false  # Add a related content section to all single posts page

  code_copy_button = true # Turn on/off the code-copy-button for code-fields
  
  # Add custom css
  # customCSS = ["css/foo.css", "css/bar.css"]
  customCSS = ["https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.15.1/css/all.min.css", "css/styles.css"]

  # Social Icons
  # Check https://github.com/Track3/hermit#social-icons for more info.


  [[params.social]]
    name = "github"
    url = "https://github.com/eddycjy"

[menu]

  [[menu.main]]
    name = "文章"
    url = "posts/"
    weight = 10

  [[menu.main]]
    name = "标签"
    url = "tags/"
    weight = 10

  [[menu.main]]
    name = "关于"
    url = "about/"
    weight = 20


  [[menu.nav]]
    name = "文章"
    url = "posts/"
    weight = 10

  [[menu.nav]]
    name = "Go语言编程之旅"
    url = "https://golang2.eddycjy.com/"
    weight = 11

  [[menu.nav]]
    name = "Go语言进阶之旅"
    url = "https://golang1.eddycjy.com/"
    weight = 11

  [[menu.nav]]
    name = "Go语言设计哲学"
    url = "https://golang3.eddycjy.com/"
    weight = 11

  [[menu.nav]]
    name = "Go语言入门系列"
    url = "go-categories/"
    weight = 12

  [[menu.nav]]
    name = "Kubernetes系列"
    url = "k8s-categories/"
    weight = 13





================================================
FILE: content/about.md
================================================
---
title: "关于"
date: "2020-03-15"
---

你好，我是煎鱼，最近沉迷于 Go、Kubernetes、Prometheus 这一生态圈子里的东西（努力学习中）。在工作中，目前主要负责公司的基础架构/组件的建设和业务团队推广， 欢迎大家来找我玩和讨论问题，提建议也随时欢迎。

### 有趣的时间节点：

1. 高一：参加俱乐部，捣鼓 Photoshop 为校学生会做做平面设计。
2. 高一：参加市/省/国赛，捣鼓前端，那是一个 table+css+js 的时代，dw 还很火热。
3. 大一：参加校组织，捣鼓 PHP，还为校组织开发了微信公众号（当时公众号刚出来），结果不错，市场占有率极高。
4. 工作三年（加上实习的时间）：在那一天，公司 CTO 突然喊我私聊，希望我去全新的业务组（哥伦布组），我一口答应下来，当时还不知道 Go 语言是什么，自此从主力语言从 PHP 转为了 Go，并写了很多 Go 语言相关的[系列](/category)。
5. 工作四年：2019 年年尾正式转到了公司的架构组，在 2020 年 7 月正式出版 Go 语言图书《[Go 语言编程之旅](https://item.jd.com/12685249.html)》，并在 2020 年的 GopherChina 拿到了 GOP 的荣誉称号。

### 联系方式：

- Github：https://github.com/eddycjy/blog
- 公众号：脑子进煎鱼了
- 邮箱：eddycjy@gmail.com

### 我的公众号

平时喜欢分享 Go 语言、微服务架构和奇怪的系统设计，欢迎关注我的公众号：

![image](https://image.eddycjy.com/7074be90379a121746146bc4229819f8.jpg)




================================================
FILE: content/go-categories.md
================================================
---
title: "《跟煎鱼学 Go》"
date: "2020-04-21"
---

我不怎么喜欢左写写，右写写，因此总是在不知不觉中写了不少的系列教程，希望对你有所帮助，若要催更请关注公众号后私聊催。

- 一：**HTTP 应用**
    - [「连载一」Go 介绍与环境安装](/posts/go/gin/2018-02-10-install/)
    - [「连载二」Gin搭建Blog API's （一）](/posts/go/gin/2018-02-11-api-01/)
    - [「连载三」Gin搭建Blog API's （二）](/posts/go/gin/2018-02-12-api-02/)
    - [「连载四」Gin搭建Blog API's （三）](/posts/go/gin/2018-02-13-api-03/)
    - [「连载五」使用 JWT 进行身份校验](/posts/go/gin/2018-02-14-jwt/)
    - [「连载六」编写一个简单的文件日志](/posts/go/gin/2018-02-15-log/)
    - [「连载七」优雅的重启服务](/posts/go/gin/2018-03-15-reload-http/)
    - [「连载八」为它加上Swagger](/posts/go/gin/2018-03-18-swagger/)
    - [「连载九」将Golang应用部署到Docker](/posts/go/gin/2018-03-24-golang-docker/)
    - [「连载十」定制 GORM Callbacks](/posts/go/gin/2018-04-15-gorm-callback/)
    - [「连载十一」Cron定时任务](/posts/go/gin/2018-04-29-cron/)
    - [「连载十二」优化配置结构及实现图片上传](/posts/go/gin/2018-05-27-config-upload/)
    - [「连载十三」优化你的应用结构和实现Redis缓存](/posts/go/gin/2018-06-02-application-redis/)
    - [「连载十四」实现导出、导入 Excel](/posts/go/gin/2018-06-14-excel/)
    - [「连载十五」生成二维码、合并海报](/posts/go/gin/2018-07-05-image/)
    - [「连载十六」在图片上绘制文字](/posts/go/gin/2018-07-07-font/)
    - [「连载十七」用Nginx部署Go应用](/posts/go/gin/2018-09-01-nginx/)
    - [「番外」Golang 交叉编译](/posts/go/gin/2018-03-26-cgo/)
    - [「番外」请入门 Makefile](/posts/go/gin/2018-08-26-makefile/)
- 二：**gRPC 应用**
    - [「连载一」gRPC及相关介绍](/posts/go/grpc/2018-09-22-install/)
    - [「连载二」gRPC Client and Server](/posts/go/grpc/2018-09-23-client-and-server/)
    - [「连载三」gRPC Streaming, Client and Server](/posts/go/grpc/2018-09-24-stream-client-server/)
    - [「连载四」TLS 证书认证](/posts/go/grpc/2018-10-07-grpc-tls/)
    - [「连载五」基于 CA 的 TLS 证书认证](/posts/go/grpc/2018-10-08-ca-tls/)
    - [「连载六」Unary and Stream interceptor](/posts/go/grpc/2018-10-10-interceptor/)
    - [「连载七」让你的服务同时提供 HTTP 接口](/posts/go/grpc/2018-10-12-grpc-http/)
    - [「连载八」对 RPC 方法做自定义认证](/posts/go/grpc/2018-10-14-per-rpc-credentials/)
    - [「连载九」gRPC Deadlines](/posts/go/grpc/2018-10-16-deadlines/)
    - [「连载十」分布式链路追踪 gRPC + Opentracing + Zipkin](/posts/go/grpc/2018-10-20-zipkin/)
- 三：**grpc+grpc-gateway 应用**
    - [「连载一」gRPC介绍与环境安装](/posts/go/grpc-gateway/2018-02-23-install/)
    - [「连载二」Hello World](/posts/go/grpc-gateway/2018-02-27-hello-world/)
    - [「连载三」Swagger了解一下](/posts/go/grpc-gateway/2018-03-04-swagger/)
    - [「连载四」gRPC+gRPC Gateway 能不能不用证书？](/posts/go/grpc-gateway/2019-06-22-grpc-gateway-tls/)

### 我的公众号

平时喜欢分享 Go 语言、微服务架构和奇怪的系统设计，欢迎关注我的公众号：

![image](https://image.eddycjy.com/7074be90379a121746146bc4229819f8.jpg)

================================================
FILE: content/k8s-categories.md
================================================
---
title: "《跟煎鱼学 Kubernetes/Prometheus》"
date: "2020-05-16"
---

请注意，这不是成品，随时可能会对以前的章节进行修改。那么为什么要放出来呢，当然是为了催更自己。

1. [Kubernetes 本地快速启动（基于 Docker）](/posts/kubernetes/2020-05-01-install)
2. [在 Kubernetes 中部署应用程序](/posts/kubernetes/2020-05-03-deployment)
3. [使用 Go 程序调用 Kubernetes API](/posts/kubernetes/2020-05-10-api)


1. [Prometheus 快速入门](/posts/prometheus/2020-05-16-startup)
2. [Prometheus 四大度量指标的了解和应用](/posts/prometheus/2020-05-16-metrics)
3. [使用 Prometheus 对 Go 程序进行指标采集](/posts/prometheus/2020-05-16-pull)

### 我的公众号

平时喜欢分享 Go 语言、微服务架构和奇怪的系统设计，欢迎关注我的公众号：

![image](https://image.eddycjy.com/7074be90379a121746146bc4229819f8.jpg)

================================================
FILE: content/posts/2020-summary.md
================================================
---
title: "拖更的 2020 年不一样"
date: 2020-12-31T21:29:55+08:00
images:
tags: 
  - 总结
---

大家好，我是煎鱼。

万万没想到...想着写 2020 年总结，结果就到了 2021 年，不愧是只有 7s 记忆的博主 😂。

2020 年并不简单，这也是第一次在公开场合写个人向，并且还是年终总结，感慨颇多。

## 出书

今年（2020年）上半年几乎没有更新博客文章，当时还一口气退了一大堆技术交流的微信群。当时有不少朋友来咨询我怎么了，后面的事大家也就知道了。

蛰伏了将近 9 个月，出了人生第一本图书（简体+繁体）：

![](https://image.eddycjy.com/56c805ff0e8c6134e845d5da99d4ab0b.jpg)

本书已印刷三次，和编辑沟通了几次，现在 Go 语言还算小众（与 Java、Python 相比较），销量算是挺不错的了。

有一块比较遗憾，在初印有几个比较致命的印刷问题。后续在第二次印刷中解决了。此次只能说第一次写书经验不足，编辑也是，下次一定。

另外当时出书时与曹大聊过几次，他提到的出书后会遇到的所有烦恼我大多都遇到了，现实太真实，出书很理想。

其次写书并不赚钱，不要见面就问。更没有因此改变我的初心，依然是热爱分享知识的煎鱼。

未曾想过的第一个里程碑完成。

## 博客/公众号

后半年就开始陆续恢复博客的写作了，2020 年博客上共有 32 篇技术文章，加上图书的稿子一年总共写了 70+ 篇文章。

2019 年只写了 19 篇。相比较而言，总产出还算可以：

![](https://image.eddycjy.com/4be8f0069f8b79388c1fe0853ab9a534.jpg)

但理论上还可以更高，因为在写完书后，由于之前过于高度集中，导致下半年出现了几个月的真空休息期。更深刻的认识到了劳逸结合，适当调节非常重要。

同时公众号也在年尾终于往前走了一步，开始接了一些推广，虽然钱不多。但更多的还是激励自己，倒逼自己更多的输入和输出。

最近有很多小伙伴也发现了我公众号的更新频率变高了，这是相辅相成的。

知识吸到就是你的。

## 社区

今年因为分享知识接触到了很多人，又因此认识到了更多的人。其中不乏各行各领域的优秀小伙伴们，间接的给我人生发展上提供了极大的建议和反馈，影响了我做许多事情的决策和思考方向。

同时在 Gopher China 2020 中拿到了 GOP（Go 领域最具观点专家）的荣誉：

![](https://image.eddycjy.com/6106728f2f69a19d5584623326c97363.jpeg)

很可惜的是，当时正在在准备公司内答辩的 PPT 和生病中，因此没能去现场，很遗憾。

不过在线下依然感受到了各路 Gopher 们的反馈和关注，很感谢 GoCN 的认可。

未曾想过的第二个里程碑完成。

## 工作

感觉自己变化太大了，发现今年思考事情的角度、广度、深度以及关联性已然和上一年不一样。

![](https://image.eddycjy.com/82d6bd939ce594c3ad219722380f5957.jpg)

经提醒也发现已入职三年半，已经到了传统定义的 “职业倦怠期” 的时间阶段，如何更好的保持自己的好奇和发展是一个要考虑的大命题。

自己评判自己的工作是很难的，继续努力是大方向。

## 读书

今年看的书挺多，涉及了计算机、产品设计、用户增长、金融理财等各个领域。

阅读时间主要是集中在午睡时间和晚上睡前看。

公司桌面上的书也是越来越多：

![](https://image.eddycjy.com/b114cdba7dc15e5175dedb83d5aa82b9.jpeg)

强烈建议阅读 DDIA，好书。

## 总结

今年经历了许多魔幻的事情，好彩大多都挺了过来并解决了。

同时也认识到了许多的社区朋友，在北京也算吃过烤鸭，冻肿过手指的人了。

最后，我时常能在私聊或朋友圈听到来自读者们的反馈：

![](https://image.eddycjy.com/c23325dd64d5eee7410647cc0e472b94.jpeg)

很感谢大家喜欢我的文字，能从煎鱼身上吸取到自己想要的知识。

希望 2021 年咱们继续努力，把 flag 都给立好了。

![image](https://image.eddycjy.com/0618aba7eb620d6541e2f02154a4ab19.jpeg)





================================================
FILE: content/posts/2020-top100.md
================================================
---
title: "吐血整理 | 快速了解全球软件案例（Top100）"
date: 2020-12-22T21:26:44+08:00
toc: true
images:
tags: 
  - top100
---

前几天，煎鱼去了趟北京，参加了为期三天的全球软件案例研究峰会（TOP 100）。

同时记了一些笔记，整理后分享出来，希望对大家有所帮助，拓展眼界非常重要。

![](https://image.eddycjy.com/a1be9ee345e57e1299f74a3d9e336d13.jpeg)

内容比较多（已经精简过），大家可以挑自己感兴趣的学习，建议三连。

一级目录如下：

1. 百度内部业务 ServieMesh 实践。
2. 云原生开发平台在腾讯游戏运营中的实践。
3. 快狗打车可持续交付实践。
4. 网易数帆从微服务框架到服务网格架构平滑演进及最佳实践。
5. 不破不立：企业级研发效能提升的创新实践。
6. 自如云原生落地最佳实践。
7. 研发效能度量的误区、体系化实践和效能提升案例。
8. 京东 BDP 的全域监控、管控平台搭建实践。
9. 构建发布效率从10分钟到秒级的提升 - 云原生下编程方式的探索和实践。
10. 全面监控体系建设及智能监控的探索实践。
11. 低代码技术在贝壳的实践。

## 百度内部业务 ServieMesh 实践

本场演讲内容主要为微服务到服务网格的过程。其中涉及百度在异构场景下的一系列演进和适配操作。

同时也能得知百度也是自己做了个 bmesh，自此概括几乎全一线互联网大厂，均为自研（或结合）ServieMesh。

### 整体演进

#### 1.0 时代

第一代微服务架构（1.0时代），主体是基于 SDK/开发框架的微服务治理体系。

![](https://image.eddycjy.com/83b5009e040969ee7b60362ad7426573.jpeg)

主要存在以下问题：
- 开发成本高：异构语言的问题，每个语言都要重新开发。
- 升级成本高：框架上线以来业务。
- 管理成本高：服务拓扑和治理没有统一管理（需要治理）。

#### 2.0时代

第二代微服务架构（2.0时代），主体是基于微服务框架到服务网格，也就是把服务治理能力抽取出来，作为一个进程（sidecar），与业务逻辑解耦。

![](https://image.eddycjy.com/ea571676ce9b75b0730a5d56350ae93e.jpeg)

从概念上来讲，主要分为以下两类：
- 数据平面
    - 与业务无关。
    - 与语言无关。
    - 独立的升级（直接升级 sidecar 的进程），能够解耦。
- 控制平面
    - 能够统一的管控。

### 百度现状

各语言在内部平分秋色，没有谁强谁弱。各自都有框架，且有可能有多个框架，可自行脑补一下在公司内部一种语言有 N 种框架，且多种协议（含私有协议）的情况：

![](https://image.eddycjy.com/182845aceb39c9e413e28fd549058cf8.jpeg)

存在以下问题：
- 多个语言开发。
- 多个框架改造。
- 多个通讯协议。

简单来讲就是 “异构系统”，传统的微服务框架无法满足了，成本非常高，甚至不可行。只能通过服务网关的方式来实现微服务治理。

### 上服务网格的困难

- 改造成本：
    - 各种内部框架的支持。
    - 各种通讯协议的支持。
- 性能问题：
    - 通讯延迟，有些敏感业务无法接受，例如：搜索。
    - 资源开源，数十万机器，每个服务都加边车，成本极大。
- 规模问题：
    - 随着接入的节点越多，规模越大，控制平面下发配置的速度越慢，甚至无法工作。
    
### 百度的解决方案（整体架构）

![](https://image.eddycjy.com/9679ccb5a92f650b83fcf29e0a6a6775.jpeg)

在开源的技术栈上进行了自己的拓展，用的是 istio+envoy。

并且在 istio 之上做了一层抽象，实现了 Mesh 的管理界面。

另外实际上在调参时，是需要很多实际经验的，例如：超时的值到底怎么配，因此又基于此在平台上提供了智能调参系统。

与目前所知的一线互联网大厂改造比较类似，区别在于还做了很多自有平台。

### 遇到的问题（大规模落地三步走）

![](https://image.eddycjy.com/ddf9c9a45551e218c4018d5c53e9f6bb.jpeg)

#### 解决接入问题
- 流量劫持方案：
    - 社区自有的方案无法修改服务治理的参数（例如：导致原有的超时重试变成了对边车重试）。
    - iptables 存在性能问题。
    - 无法在 mesh 和 非 mesh 下切换：不能完全信任，挂掉后怎么处理，流量怎么切。解决方案是劫持服务发现的过程（边车劫持的是的服务地址），就能够解决流量劫持的自由问题。
- 自有协议代理：有二十多种协议，解决方案是抽了一层公共 Proxy，实现 codec 就可以了。但也没法解决全部问题，因为 Mesh 对协议有要求，例如加字段。但有的老协议是没法扩展的。最后解决方案是做协议转换，业务代码就不需要修改了。
- 多框架支持：网格对框架有基本要求（治理行为可拓展，透传 Trace 信息），但有的老框架没法支持。通过探针逻辑修改框架行为（探针感知逻辑，修改框架行为）。

#### 解决性能问题
- 网络性能优化：
    - envoy 的最大问题是性能不怎么好，拓展性是第一，性能是他的第二位。
    - envoy 的多线程的竞争是非常厉害的。最后是采取 envoy+brpc 的融合方案（难度很大，组件替换，逐步替换）解决，整体延迟和 CPU 使用率明显低于原生版本。做了开关，能在原生和融合后版本切换。
- 网络控制面优化：
    - istio 原生的配置是全量下发的，非常不科学。
    - 改造为通过获取关系按需下发。服务发现改为由控制面下发到数据面。简单来讲就是原生 istio 控制面在大规模下有很多问题，为此改了很多逻辑。
- 网络性能优化：
    - istio 原生为 both side 模式，要转换 2 次，损耗 2 次网络开销，2次性能开源，内部认为不可接受。改为 client side 的模式（架构上的折中，有的业务很敏感，不推荐为主流方式）。

#### 享受网格的红利
- 流量可操控：
    - 所有的流量都在自己的手中，可以去做很多事情。例如做很多动态的事情，全局流控，根据延迟分配请求到不同的下游等，带来的新的问题就是太多配置，太吃经验，因此做了哥全局智能调参。
    - 结合高级治理，配合自愈和剔除，可用性的修复时间大大的提高，提高了可用性。
- 服务可观测：
    - 结合框架透传 Trace 信息，Sidecar 负责上报监控，即可形成追踪。
- 自动止损
    - 结合监控平台采集实例、集群信息，发现异常，上报给控制平面。然后就可以屏蔽掉某个实例、集群。实现自动止损。
- 异常注入
    - 混沌平台负责配置、评估，服务网格负责实施异常注入。
- 容量管理
    - 传统需要做压测，对整个系统进行很长时间的压测（想压到极限，要构造大量的数据和流量），非常麻烦。
    - 通过服务网格可以在局部构造出极限的压力。

### 落地情况

百度目前正在逐渐落地，已接入实例数万。通过高级的服务治理（需要自实现）带来了很大的收益。

但需要注意，如果只是单纯接入服务网格，并不能带来上述所说的收益。他的收益更多的是面向后续的一些高级治理等高级场景。

### 总结

- 服务网格不是微服务治理的银弹：
    - 完全无侵入支持所有空间和治理策略的 Mesh 方案是不存在的。
    - 大规模落地一定会涉及已有治理的兼容升级和改造。
- 服务网格确实实现了业务逻辑和服务治理架构的解耦。
- 服务网格的开始是最难的，落地服务网格会非常困难和艰辛。

### QA

- 第一个：
    - 新产品可以上服务网格，但要有一个现成成熟的服务网格，自研工作量是非常之大的。
- 第二个：
    - 和开源社区结合的问题，会不定期更新 envoy，istio 的版本。
    - 服务网格不能只看节省的成本，如果只是说框架的治理，那是非常小的，最大的收益是把所有的流量都汇总到一起后收益非常大。网格一开始会非常痛苦，需要把流量真正的拦截上去。
    - 边车的定位是服务于服务之间的通讯代理，与业务逻辑比较紧耦合是不适合放进去的。
    - 推广的目标不是全站覆盖，核心链路上到就可以，因为有的应用对这类没什么诉求。
- 第三个：
    - 是否 SSL 看企业场景。
- 第四个：
    - bmesh 可以从全局角度监控，现有的监控模式可能你会是自己有问题。


## 云原生开发平台在腾讯游戏运营中的实践

- 平台的期望：提高研发效能，业务落地成长。

- 业务背景：营销活动，上线活动很多是不报备的，因此伸缩性要求高，日活很容易上千万。活动多（每天新增 50 个以上），数量量幅度大，服务质量要求高。

- 实际成效：这么大的规模，现在只需要 3 个 专职运维，晚上 6 点就下班了。

### 本质需求

- 频繁发布：版本发布更新。
- 动态伸缩：数据量大。
- 持续高可用：经常变更。

### 运维的任务

![](https://image.eddycjy.com/aba4c12c0307ac56aedf5e7b2dadf69b.jpeg)

以往都是开发提交给运维的，问题是有极多个开发对接有限的运维。面临的问题：

- 面临的环境，部署的东西，都是不是固定的。
- 开发需要转移知识给运维。
- 实际经常会出现意外情况。
- 对部署的风险：运维本能排斥变化。

呈现的结果是运维忙于救火，开发提个需求，就只能排队，线上总不稳定。

### 解决办法

- 持续交付：
    - 控制产品发布节奏，需求尽快上线，不积压。
- 打造部署安全网：
    - 微服务、并行部署，完善的监控。
- 实现可重复性：
    - 控制环境和部署的构建，自动化， 保证输入输出的一样的。
- 变化是必然的：
    - 以故障是常态去设计。

### 碎片的解决方案

要解决上述所提到的问题，基本目前在业界都有基本的解决方案，但其都是 “碎片化” 的，如下：

![](https://image.eddycjy.com/4f84f02beb6427bc9a6d8d09d2376746.jpeg)

“碎片化” 指的是不同的组件都分别是解决特定的问题。这就导致了下述问题：

- 各方面的学习成本高。
- 系统自动化程度低。
- 有经验开发人员有限：
    - 人员招聘成本高，限制发展规模。
- 无生命周期：
    - 整体的上线到下线没有管理。

### 云原生开发平台的设计

真正的完整解决方案就是做一个 “云原生开发平台”，提供一整套的服务来支持软件的开发和运维，实现各种云原生软件的诉求。

从设计角度上来讲：

![](https://image.eddycjy.com/02519bfb266773f243fdef49420313d1.jpeg)

运维不暴露太多的基础建设，只是开放角度去做。开发人员只需要关注应用程序，不需要关注底层的基础设施。

不需要让业务关注你用的是 k8s、envoy、gitlab 什么基础设施，不用去学习一些特定的知识体系。

### 资源评估中心化的运维

![](https://image.eddycjy.com/549cfc258b5b09317e51edf0d640cf8d.jpeg)

开发需要申请资源，运维需要评估，分配，再审核执行。最快是小时级，是平台的瓶颈。

![](https://image.eddycjy.com/f7f163af78812e58c4d3c47b4e396ae6.jpeg)

解决方案是把资源分片，实现团队自治，开发就可能承担了部分运维以往的工作。

此时又会带来由于运维部分工作转移到开发后的成本问题，这部分就需要由平台来解决，提供下述全流程：

1. 智能的容量评估
2. 自动化提单/审批
3. 自动下线（通过日志、性能、调用来识别）
4. 自治并释放资源。

最终的成效是目前所有的审批都是业务团队自己去做，运维只负责供应资源。

#### 微服务下的依赖问题

思考：服务 A 流量上涨，依赖的服务如何扩容？

![](https://image.eddycjy.com/d077e4317cde1e70737c7d5616929159.jpeg)

利用 istio 做全链路分析，实现全自动化，精准识别出入流量，计算差异部分，就能知道改变的服务链路和所需放大的倍数。

### 实现可重复性

应用跑不起来，肯定是有东西改变了：

- 环境控制：镜像。
- 构件控制：全自动化流水线，例如：代码版本、编译命令等。
- 运行时配置：提供配置管理，实现版本控制。

控制可运行时容器，就可以做一系列工作。系统提供默认安全，应用也就安全。

### 变化是必然的

面向故障设计：
- 多可用区可用（异地多活？）.
- 主机故障自愈/剔除能力。
- 实例守护剔除能力。
- 配置恢复能力。

### 开发阶段如何提升效率

做了个服务市场，业务应用。沉淀利用现有的能力。

### 总结

基础设施，团队自治，统一且自动化的交付。开发运维一体化，转移到开发的成本，要用平台来解决。

### QA

- 第一个：
    - 故障定位，看基础设施，若是软件业务逻辑，软件业务逻辑是通过平台来提供工具来支持业务排查，帮助定位，大部分还是靠业务团队做的，若是基础设施基本都是大面积的。
- 第二个
    - 版本一致性，必然存在，发布有先后顺序，可以走蓝绿，业务逻辑也要做一些兼容处理。
- 第三个
    - 去抖动下发的策略，会持续监听 IP 并收集，配置下发有最小的间隔，例如十秒间隔的统一下发（存在一定延迟）。又或是到了一定数量级也会下发。不会来一发触发一条。
- 第四个
    - 开发要对利用率关注，压测，让平台上能够自动化去帮他实现，帮助他认识，自动生成出建议的数量和规模。同时服务的流量是分高峰，平峰的，平台要有提供自动扩缩容的机制（例如：也可以做定时策略）。支持自定义指标的扩缩容，要有一个超卖的策略。
- 第五个
    - 研发和运维的分界线，版本上线的告警目前都是由业务自己做的，代码是业务自己写的，暗含的逻辑运维必然不知道。开发要做全生命周期的跟踪。
    - 统一网关不包含业务逻辑，更多的是支持公有云私有云，私有协议，一些登陆。业务网关更多的是跟业务相关的。
- 第六个
    - 长连接如何做无损发布，超过 30s 后 ipvs 感知不到连接断开，流量还是会分过来。存在局限性，要感知协议类型（内部做了针对性的自动化判定），判断流量是否结束，若结束则转发到新的。四层还是需要业务自己实现的。

## 网易数帆从微服务框架到服务网格架构平滑演进及最佳实践

介绍微服务相关的理念和服务网格的演进，前半部分非常高关注率，听众大量拍照。

后半部分主要是网易轻舟的产品和技术介绍，主要是偏向 Java 方向，因此主要是在思想上进行参考，有一定的价值意义。

从 2017 年开始进行 ServieMesh 的研究，不断进行打磨，直到 2020 年正式释出网易轻舟这一个技术产品。

### 为什么要从微服务框架演进至服务网关

在 2012 年正式提出微服务，介绍了微服务的发展史：

![](https://image.eddycjy.com/e02b5f50d064103233b3adee3b96a510.jpeg)

- 1.0时代：2011-2017，以框架为代表的微服务框架。
- 2.0时代：2017-至今，以服务网关为代表，业务与治理解耦。

### 微服务框架存在的问题

1. 适用范围。
2. 升级成本。
3. 侵入性。
4. 治理能力有限。
5. 框架负担。
6. 架构演进与云原生相冲突（注册中心部分）。

### 服务网格的定义和优势

服务网格定义为服务间通讯的基础设施层，通过轻量的网络代理进行拦截和处理。堪称异构语言的救星。

### 服务网格的技术升级改造成本

思考：我真的需要服务网格吗？

![](https://image.eddycjy.com/dcf816fe7054b0a74c353321030b73ce.jpeg)

1. 业务诉求是否只能用服务网格解决？
2. 业务现状是否满足网格接入条件？
3. 业务团队是否能够驾驭得了服务网格？
4. 是否有开发配套的基础设施？

### 演进的成本问题

ROI 策略，做成本分析。

![](https://image.eddycjy.com/b06e00b230527202d3420d52eb4760e1.jpeg)

### 接入诉求

![](https://image.eddycjy.com/74cde9d40b00ceea6d10db88ce9a1512.jpeg)

要关注业务期望收益是什么？

### 微服务框架和服务网格共存

- 微服务框架：面向应用内的服务治理。
- 服务网格：面向服务间的服务治理。

微服务框架和服务网格两者存在重合的区域，但又无法完全替代：

![](https://image.eddycjy.com/46bf4496d08a7627f25dbf5588cfbfd4.jpeg)

网易轻舟的平滑演进主要是针对 Java 系，对此 JavaAgent 做了一些调整（如下业务迁移），以此来实现平滑演进。

### 业务迁移

微服务框架 =》 融合（过度）期 ：存在流量管理的能力冲突 =》 服务网格

逐步分离，缓慢实现技术升级。方案分为：
- 通过 JavaAgent 迁移。
- 通过网关做灰度流量迁移。

### 服务网格与真实的使用场景差异

设计上比较理想化，很难直接拿来给业务直接用，业务真正使用都要做定制化改造：

![](https://image.eddycjy.com/8478ec28fa40c5f169aa51aa9b461b1d.jpeg)

为了解决这些问题，网易轻舟做了以下增强：
- 通讯协议增强支持（例如：Dubbo、Thrift）。
- sidecar 的管理问题：每次的升级问题，社区方案每次都要重启 pod。网易轻舟是实现了热升级。
- 多场景的限流方案：社区方案的性能常被人吐槽，并且场景支持不充足。
- 基于服务网格的能力拓展：例如：监控。

提供微服务框架和服务网格的一体化的控制台，简单来讲就是通过平台将用户的业务改造成本和学习成本和运维成本大幅度降低了。

因此平台化是解决服务网格 “成本” 的一个出路。

## 未来

- 中间件 Mesh
- 排障体系建设
- 故障演练体系

## 总结

认为落地过程一定是曲折的，服务网格未来一定会是光明的。

细节会是魔鬼。

## QA

- 第一个：
    - 微服务框架到服务网格的最大难点：解决服务发现的过度问题，如何把注册中心打通。
- 第二个：
    - 2017 年开始关注投入，不断打磨，到 2020 年才出现网易轻舟。因为官方也不断在演进，他们也在不断演进。
- 第三个：
    - 中间件 Mesh，性能影响？目前主要还是偏向监测，访问成功，错误率，流量，使用的，偏向监控方面的设计。
- 第四个：
    - 现在遇到的业务诉求是否一定要用服务网格去解决？以及内部是否认同服务网格？


## 不破不立：企业级研发效能提升的创新实践

会场全场站满，讲师很有趣，经历丰厚，是研发效能的出品人。其介绍了许多研发效能和度量相关的知识和理念。

同时驳斥了现在业界很多的一些基本的理念，让人深思。

### 为什么研发效能火了

为什么以前研发效能都没法塞满一个会场，为什么现在出现如此盛况？总的来讲是时代变了，商业逻辑变了，大家对研发效能有了更大的理解：

![](https://image.eddycjy.com/679db6b81a9bf927f70c81bd1418fcff.jpeg)

靠信息不对称，对称后如何在研发这一侧如何快速的交付，同时要高质量，既要又要。

### 研发效能的五大 “灵魂拷问”

概括研发领域的现象，如下图：

![](https://image.eddycjy.com/3cac50b8521ddc22bcf9624ec7ee5693.jpeg)

拉车的人（代指：老板）没空看轮子，不知道轮子是不是方的，而推轮子的人是我们工程师。你知道不知道轮子是什么形状？

#### 第一问：研发团队的忙碌能够代表高效率吗？

![](https://image.eddycjy.com/ac6a5cba95ed68e30ff314a0f028d4c9.jpeg)

例如：凌晨半夜三点修 BUG 的人一定是最好的吗？BUG 很有可能是他埋的，他不修谁修？

建议方向：
- 架构的长期规划。
- 中台的持续沉淀。

#### 第二问：敏捷是研发效能提升的银弹吗？

![](https://image.eddycjy.com/2ddb582a11acd6f750cc3f46aaa54520.jpeg)

敏捷指的是能更快速的尝试，有问题的话马上调头。敏捷是要做小船。

#### 第三问：自动化测试真的提升软件质量了吗？

![](https://image.eddycjy.com/86c11968fd3789c7f65b488447106dae.jpeg)

如果卡死自动化测试的覆盖率没意义，最后会变成覆盖率很高，走的很慢，因为让覆盖率变高有非常多种方法。

而卡死自动化测试，就会导致没有精力去做探索性测试，更多的测试。需求变了，自动化测试又变了，又要花时间继续做新的自动化测试。。

自动化测试只是个手段，不是目标。新功能不应该做自动化，**功能本身趋向稳定了，才应该去做自动化测试，成本才低，成就感才高**。

#### 第四问：没有度量就没有改进，这是真的吗？

![](https://image.eddycjy.com/b49cb46586a53de77a562fcba314527e.jpeg)

研发效能很难在真正意义上度量，软件研发是创造性的劳动，不同的人来做是不一样的，硬要做，就会变成你度量什么，工程师就做什么。

你度量钉子，那你得到的就是钉子。你度量什么，就一定会得到什么。

不要用来考量 KPI，否则千行就会变成万行，要慎重。

#### 第五问：研发效能的提升一定是由技术驱动的吗？

![](https://image.eddycjy.com/358b682fb20ba6b54769b3a0c1186138.jpeg)

不要陷入局部思维，真正的问题不是单点的问题。

例如：看医生，真正挂号多久，但你真正花时间的是排队，看完医生1分钟，又开单验血，又等。因此等待时间是最大的。

在软件领域中，也是在等待时常上花的时间最久的。是部门墙，信息不对称导致的问题。

### 研发效能到底是什么？

![](https://image.eddycjy.com/df4963c29b6fa4cf6d452093b43ddf00.jpeg)

先有的现象，再有的结果，定义。

### 研发效能提升的案例

- 前端代码的自动化生成。
    - 工程师在白板上画 UI，自动识别并生成出代码和界面（利用了 AI 的相关技术）。
- 临界参数下的 API 测试
    - 自动的测试数据生成。
- 微服务架构下的环境困局。
    - 公共基础环境的问题，高效的方法是做公共基础环境，也就是现在的云端环境。每天和生产环境同步。

### 研发效能的第一性原理

![](https://image.eddycjy.com/a74a6f1aa5e19ac991402597853ed1d2.jpeg)

顺畅，高质量地持续交付有效价值的闭环。

- 做有价值的东西，做用户需要的，不要做用户不要的。

- 凡事做的事情能让这五个 “持续” 提高，就算研发效能。

- 所有的过程改进要用数据说话，但不要用来考核。

### “研发效能” 的点点滴滴

![](https://image.eddycjy.com/d0abd507792ff6c98882b5887ddfe2a0.jpeg)

研发效能的点点滴滴，做这些都能提高，针对性举例：

- 例如：云 IDE，非常方便。

- 例如：（举例 sonar）sonar 的机制为时已晚，没什么意义。可以在本地就去跑 linter，走得快质量还高。

- 例如：代码复杂度，最终呈现的就是软件和架构的腐化。研发工程师就开始复制粘贴改，最后没几年就废了。

- 例如：代码递交规范，你会把需求id带进去吗？不带的话，后面所有的度量都没法做，追踪都没法做，拿不到需求 id 都没做。

- 例如：分布式编译，各个模块分散到分布式去编译，从十分钟变 10 秒。

### 研发效能提升的一些经验和实践

![](https://image.eddycjy.com/57a3b325f949fc24b03ab1db8b221f89.jpeg)

推荐看书，用 MVP 思想做，和做通用工具完全不一样。

研发效能要先发现钉子，再去找锤子。和做通用工具不同，工具是拿锤子找钉子。

研发效能一般采用逐渐扎小孔，一层层做的模式。每次给的功能点足够小，但每一次给的都有价值。

![](https://image.eddycjy.com/6b574fba0ab6c360e3a2b5440f7450e1.jpeg)

做 MVP 不是横切一刀，是包含各方面的斜切。

![](https://image.eddycjy.com/c7cd61c07e131800a9febaa8ba675b65.jpeg)

这部分内容太太太多了，讲师也没有讲完。下方为根据讲了的部分整理：

- 从痛点入手：
    - 测试数据的搭建统一到测试数据中台去做。
    - 如研发度量的数据获取是最重要得，例如由工具自动触发状态的改变，而不需要研发工程师去调整，且获得的数据是真实有效的。
- 从全局切入：
    - 例如：一个 BUG，真正修复的时间是多少？
- 用户获益：
    - 让用户获益，是研发效能的核心
    - 不要你以为业务团队要，业务团队关心的是温饱问题。例如：你就看看业务团队自己有没有在搞，他们有在搞，这就说明是真的需求。
    - 结构很重要，如果设计的体制要每个人都大公无私是必然失败。每个人越自私越自利越能成功。举了和尚分粥的例子。
    - 谁接入了多少不是最重要的，是业务得到了什么。
    - 服务意识，早期保姆式服务，沉淀后，就是双赢，
- 持续改进
    - 例如：GitHook 直接调 JIRA API 不是最好的方案，没有版本管理，规模大了绝对不是好方法。
    - 应该走消息队列，揭藕。平台化。
- 全局优化
    - 下层提出，上层认可。
- 杜绝掩耳盗铃
    - 虚荣性指标 vs 可执行指标
    - 例如 sonar 接了多少个项目，就是虚荣性指标。应该考察可执行指标，例如严重 BUG 存在了多久。
- 吃自己的狗粮：
    - 自己的产品你都不用，别人更不可能。

### 研发效能的未来

![](https://image.eddycjy.com/3e02bf64de89130bdc29fe5d5a69cb60.jpeg)

表达核心观点：“敏态” 和 “稳态” 一定是齐头并进的。

## 快狗打车可持续交付实践

主要面向测试环境治理的演讲，Devops 不是单纯的技术问题，整体来看 Devops 是一个复杂的混合问题。

### 理想与现实

快狗打车前期是存在固定的多套测试环境，测试环境相互影响。测试同学 A 用完环境，第二天给了测试同学 B，B 同学发现有问题，又找回 A。A 同学又认为不是自己的问题：

![](https://image.eddycjy.com/a1935c4d63890b97e5639c5723f49f4e.jpeg)

### 测试环境V1

早期测试环境的具体表现，主体为稳定环境全量部署，下分四套环境，根据需求部署：

![](https://image.eddycjy.com/d8ccd7a945a1389126d4c13771ba79bc.jpeg)

早期几十个集群还没什么问题，等到规模变大后几千个集群后问题就会很严重。同时测试人人都有管理权限，第二套变更后，会同步到稳定环境，那么其他几套环境的同步由谁负责（他们早期是手动维护）。

![](https://image.eddycjy.com/14361c5532b6b7ae6df55890b90788f7.jpeg)

另外并行需求多了就会发现固定的测试环境不够用。呈现的结果是投入产出比差异过大，各配置互相影响，稳定性很差，最终造成的测试结果也不稳定。

### 理想的测试环境是怎么样的？

- 即点即用
    - 任何时间都可以部署，并不需要排队。
- 自动隔离
    - 任何环境都是相互隔离的。
- 依赖关系
    - 系统自动解析，根据配置自动部署依赖上下游，使用者无需关注。
- 缩放自如。
    - 资源池管理，资源弹性伸缩。
- 独立闭环
    - 独立部署，无需跨部门沟通（不用找运维要资源）。

### 第一轮的优化实践

核心要点：规范、格式、自动。

![](https://image.eddycjy.com/d05babd370f63589d17cd767370d2f7a.jpg)

针对各服务做依赖关系的自动解析。细则如下：
- 制定了配置文件的格式规范，用于扫描上下游依赖，层层扫描，最终得出整体的依赖图。
- 规范要符合公司现状，绝大部分都能适配，只有让小部分的人要改。
- 服务按照类型优先级部署，这里结合了应用信息（上层应用服务，底层应用、数据库、Redis 等）。

### 测试环境 V2

只有一套稳定环境，剩余的都可以按照需求来拉环境。但存在服务直连的情况，导致出现流量拦截和调动有问题。

属于企业内部自身的债务问题了，不展开赘述。

### 测试环境 V3

结合基础架构组，最后实现按需部署，谁开发谁部署，不改动不部署。

属于企业内部自身的历史债务问题了，不展开赘述。

### 总结

在治理优化实践上一共做了如下：

- 测试环境的服务按需部署。
- 依赖环境的自动解析。
- 部署资源池管理：评估部署所需资源，再通过资源管理平台，统一资源的调度。
- 自动流转与执行：Nginx（vhost、location）、域名（独立域名、泛解析）、MQ、堡垒机等的自动申请、审核。
- 资源自动回收：需求完成上线后，需求所关联的都自动释放，又或是回收到资源池。

整体上来讲，技术不是难点，最难的是人与人的沟通，例如：跨部门的沟通，最重要的是方向、坚持、执行力。

### QA

- 第一个：
    - 测试环境数据库也没有采用按需，因为测试环境数据库不是主要痛点（矛盾点），主要权衡的是投入产出比，因为并不是建起数据库就能解决的，还要造数据，各种成本很高，结合权衡没往这个方向做。
- 第二个：
    - 资源低于 60%，则针对于已经完成上线的机器，并不是资源池内的。
- 第三个：
    - 部署的互相依赖和网状结构，通过打标签的方式，若已经部署了则不会再部署了。
- 第四个：
    - 资源平台优化策略，目前正在转向 K8S 这类云平台，后续不再自行关注。
- 第五个：
    - 公共组件是否也是重新部署，目前 redis 是重新部的，主要是针对 mysql、redis。kafka 这类是没有独立部署的。
- 第六个：
    - 最大的困难是什么，是 “人”，人的认知，达成全员的共识，为什么做这件事情，讲清楚，比做什么更重要。

## 自如云原生落地最佳实践

主要演讲内容是自如的云原生演进之路，如下：

![](https://image.eddycjy.com/6ec794425d71b36638c5d967256baa76.jpg)

当时存在大量的问题，进行了调研。结果提示低 NPS（-44%），也就是 100 个里有 52 个人对 CI/CD 系统不满意。

具体的痛点：
- 运维人肉运维。
- 生产、测试环境不一样。
- 分支合并漏发代码、漏发配置。
- 上线发布一台台点。
- kvm CPU 使用率低。

进过调研和选型，发现开源的均有缺点，最终选择自研一站式研发平台。主体功能结构：

![](https://image.eddycjy.com/c80ee685792aa265366b5cea0d3f91d9.jpg)
- 上层的平台服务：面向开发同学。
- 下层的 K8S 等：面向 Ops 同学。

平台在整体的设计边界和原则上如下：
- 边界：只做无状态应用的容器化。
- 原则：能放到平台的操作坚决不用人。

### 容器化后遇到的问题

容器化后一堆新的知识 pod、ingress、service，网络模式也变了，开发同学都不懂，产生了大量的成本（学习、运维等）。

因此就决定了做应用平台，也就上面提到的平台服务。流程图如下：

![](https://image.eddycjy.com/66886bf86b9217dc0fcb92fb7a5d6ff2.png)

### CI/CD

- 定规范，统一环境。
- 定分支，统一分支模型。
    - 在各个 feature 分支上进行开发。
    - release 分支环境用于集成和发布。
- Dcoker/Deployment 零配置
    - 根据创建应用所填写的信息自动配置，研发不需要关心。
- 工具-跳板机
    - 在平台上做跳板机，不需要关心 IP，也不用登陆。

### 总结

- 云原生平台化，运维 0 参与。公司标准化（环境、分支等）。

- 不要闭门造车，统一思想，走 MVP（步子不要迈的太大）、持续运营、持续关注 NPS。

### QA

- 第一个
  -  流量染色，是为了动态的的调控服务调用。
- 第二个
   - 数据库污染，利用账户体系来做。同时注意 mq 这类需要隔离。
- 第三个
   - webshell 创建 bash 不要太多，超过 32 个会有问题。产生僵尸进程。
- 第四个
   - 微服务到云原生的成本，学习成本必然，把 dev 和 ops 放到一起。
- 第五个
    - 目前自如是让业务在平台上配一个专门的探活接口，再去探活。
- 第六个
    - 最大的阻力，就是人，CTO 把基础架构把运维放到了一起，形成了互补。组织结构要先调整。


## 研发效能度量的误区、体系化实践和效能提升案例

Devops 专题的出品人，会场火爆，全部站满。开局表示现在已经不再是讨论要不要 Devops，而是讨论怎么去做。

讲的很好，会场人员认可度高。

### 研发效能的情况

- 你的研发效率在业界属于什么水平？与竞争对手差距？
- 敏捷转 Devops 的转型有没有效果？是否可以量化评估吗？

### 软件交付效能的度量指标

![](https://image.eddycjy.com/f4b2db7fb494a5eaea9fdd5d79f8409a.jpg)

- 部署频率。
- 变更前置时间。
- 服务恢复时间。
- 变更失败率。

### 研发效能评估（愿景）

#### 阿里（211）

- 需求 2 周内交付。
- 变更 1 小时内完成发布。
- 需求 1 周内开发完毕。

#### 腾讯

- 项目团队规模扩张控制在 20 人以下
- 迭代周期在 1 周内

#### 研发效能度量的原则

- 结果指标 > 过程指标。
- 全局指标 > 局部指标。
- 定量指标 > 定性指标。
- 团队指标 > 个人指标。
- 指导性，可牵引行动。
- 全面性，可互相制约。
- 动态性，按阶段调整。

### 工具链网络

![](https://image.eddycjy.com/eefc72a3c3125e995459d7737016ee56.jpg)

- Devops 工具链网络：强调 “网络”，工具与工具的关联，代码与需求，代码与合并，与编译，各种信息能不能追溯到下面所有的环节（把工具串联集成起来）。而不是单单管理某一个领域。
    - 项目协作域。
    - 开发域。
    - 测试域。
- 价值流的交付模型：要从用户、客户的视角去看，从端到端的角度去看，而不是开发、测试的角度。要从完整的一个用户需求提上来每一步的具体步骤。
    - 工作流。
    - 生命周期。
    - 流动效率（不是资源的占用率）。
- 效能度量分析模型：软件研发效果，最终思考的是组织效能、业务结构。
    - 交付效率：需求前置时间、产研交付周期、需求吞吐量。
    - 交付质量：变更成功率、线上缺陷密度、故障恢复速度。
    - 交付能力：变更前置时间、部署频率。


给出了分析模型里的大量的度量考察指标，并表示企业内部有更多，几百个。但要注意度量指标不在于多，在于精。不同阶段也不一样，要有北极星指标。

![](https://image.eddycjy.com/a8925088b7aeecaabf6e90c843f90a4b.png)

你做的实践不一定代表有用，但要不断地思考和实践并改善。例如单元覆盖率，有个公司永远在 80%+，后面发现是对 KPI 战法，甚至单元测试里没有断言（多个讲师提到）。

不仅要关注创造价值的工作，还要关注保护价值的工作：
- 业务需求。
- 产品需求。
- 研发需求。

### 企业内部实践

展示了京东内部的研发度量系统，看上去非常完善，可以进行多层次的下钻（事业部 -> 项目组 -> 研发人员）：

![](https://image.eddycjy.com/b36d995cc4f347bb6b7114fe4e515eda.jpg)

### 总结和避坑

- 成本问题：看板里的数据，如何让度量更准，那就是标准，那就需要大量培训。让需求和代码有关联，自动触发变更状态。自动化。
- 避免平均值陷阱：类似长尾问题，尽量用分位数。
- 度量不是为了控制，而是指导改进：如果是 KPI，你度量什么就会得到什么，只是不是以你所希望的方式得到的（古德哈特法则）。

总结：**那些不懂数字的人是糟糕的，而那些只看数字的人是最最糟糕的。应该走下去看具体是什么达成的，走到工作现场，看看是否真的有改进**。

## 京东 BDP 的全域监控、管控平台搭建实践

### 基本介绍

基于 Prometheus 生态进行了大量的改造：
- 采集端改造：PushGateway 会推数据到 Kafka，再另外消费。
- 模块拆解，作为不同的角色，读写分离，便于扩展。
    - 数据采集。
    - 预计算。
    - 数据分析。
    - 监控告警，
- 多级缓存：监控数据的数据是短时间内不会变的，会进行缓存（不同业务可配不同）。
- kongming 服务：基于不同的 promql 决定执行什么策略，例如：实时作业、离线任务、集群调度等。相当于是一个拓展了，高级监控治理了。

### 监控实践

- 单点监控：常见面板，
- 组监控：业务提供黄金指标，自动生成对应的组监控，可以做到千人前面。
- 关系链监控：父级节点和大表盘。

### 平台实践

平台提供让业务选择，业务不需要关注底层的表达式：

![](https://image.eddycjy.com/e9c2893dad1a97389131018582d6fdeb.jpg)

在更具体的实践上：

- 告警通知：支持父子节点的通知。

- 告警通知：支持告警人的动态通知，支持业务在上报指标时指定的。

- 高级治理：利用所拓展的 kongming 模块，做了许多基于历史数据和现状的干预，例如：实时作业干预、智能调度（削峰、自愈等）。也就是相当于 “人工智能” 的那一块相关内容了。

总体来讲，做自动化也会是类似的思路，要拓展出一个模块。这样子你做什么都可以，只要基于 Prometheus 的一些表达式和数据源就可以了。

### 总结

监控系统不仅要能发现，还要哪能解决问题，监只是手段，控才是目标。

解决各种人力问题。

## 淘宝系 - 云原生下编程方式的探索和实践

### 淘宝现状

![](https://image.eddycjy.com/2e85139d64d801a8b20cfe1439262689.jpg)

- 中心化：微服务化。

- 去中心化：FatSDK，以 SDK 的方式提供能力。能够保障稳定性和性能。淘系绝大部分都是采取的第二种模式。出问题的话，就只有你自己的服务有问题，不会影响其他依赖方。

在 SDK 上他们只提供 Java，其他你自己想办法，常见的可以做个代理。

### 通用能力下沉

把原有 SDK 的能力剥离到独立的进程，而不是像原本那样沉淀在应用中：

![](https://image.eddycjy.com/e92806927597cbe146488d698ef02eea.jpg)

利用云原生的容器，提供运维能力容器，业务能力容器，解决中心化的问题。在此书其实是参照了 ServiceMesh 的方式，走 Sidecar 就好了。

### 解决多语言问题

加多一层，提供 GRPC API 来进行对接。对于业务来讲只需要面对标准化的 API 就可以了：

![](https://image.eddycjy.com/767257e017a6a496a0d4f116e8cd5277.jpg)

业务不会直接对外对接暴露，所有东西都是通过对外/对内的中间层来进行衔接：

![](https://image.eddycjy.com/2709782851a3590f94711996866a4022.jpg)

### 开发市场

做了一个应用市场，业务开发可以提供组件能力上去，避免重复造轮子：

![image](https://image.eddycjy.com/4737ce38878a622436193d91f931d245.jpg)

## 全面监控体系建设及智能监控的探索实践

PPT 内容比较抽象，简单来讲：AIOps = 大数据+算法+运维场景。

通过各项能力，建设了对于历史数据的分析，做了各种分析和告警合并等场景。每个模块都大致讲了，但均没有深入讲，只能大概听个响，与原有所知的监控思路基本一致。

智能运维业界目前没有开源方案，都是一线大厂分享的经验。放一张 PPT 图：

![](https://image.eddycjy.com/a52c0e553978fd959973f9c56081b963.jpg)

按分层自下往上看，基本是基于数据进行智能化的预示来达到效果。

## 低代码技术在贝壳的实践

![](https://image.eddycjy.com/f0f5c4b8cd9416272e2d3fa4b72c2cf4.jpg)

更具体的演示效果可看平台方发的视频（期望/现状）。


### 提效

![image](https://image.eddycjy.com/c94415916dbd8d3c1ede248b9b5ef4ca.jpg)

能覆盖到的场景基本把前端功效给去掉了，但同时后端的工作量会加大。

### 现状

- 河图1.0：已开源。定制化需求，一开始想让客户自己开发插件化，效果不行。最终决定走向智能化。

- 河图2.0：智能化。
    - 期望：自动识别设计稿，国外有，支持多端。
    - 目前：
        - 贝壳现在支持的是上传 sketch 设计稿，支持不同的 iOS，安卓，Flutter 以及自己的小程序。
        - 支持后台管理增删改查，小程序，中后台等。
    - 未来：
        - 后期会引入智能化，将会持续开源。

### 投入的人力

- 第一期：最初是3个人，做了两年，从 2019.1 做到 2020.12。
- 第二期：目前投了 10 个人。

### 复杂场景

- 第一类通用类：
    - 目前可以解决。
    - 例如配置系统可以用。
- 第二类定制化：
    - 要靠智能识别。
    - 目前的确只能解决一些通用常见的问题，复杂问题还需要人来解决。

## 总结

目前业界中其实存在着大量的方案和思路，很多大厂其实更多的会根据目前公司内的实际情况进行选型和设计。听这类会议/培训，一定要关注的是其解决思路和途中的思考，是为什么这么做，踩过什么坑，比较重要。

希望大家在看完后都能有进入心流的深度思考时间，那样你才能消化到知识，并转换到你实际的工作中去。


================================================
FILE: content/posts/2021-ecug.md
================================================
---
title: "推荐一个牛逼的技术社区！"
date: 2021-01-05T21:26:50+08:00
toc: false
images:
tags: 
  - ecug
---

相信我的读者中不少是 Go 语言的爱好者，又或是正在伺机而动。

今天要给大家所介绍的这个技术社区，就是由与 Go 语言有很浓厚的缘分的人所创办的。

他有如下几个业界标签：

- 早期的国内 Go 语言布道师。
- 早期在公司内大规模的推广和使用 Go 语言。
- 早期编写了一本 Go 语言图书：《Go 语言编程》。
- 现在是一家公司的 CEO。
- 近期在大力推广 Go+。
- ...

他还有非常多的标签，通过上述这几点，你是否猜到是谁了呢？

![](https://image.eddycjy.com/0c8ac8602cca4e19c8caca30ac991305.jpeg)

没错，他就是七牛云的 CEO 许式伟。

## 与 Go 语言的渊源

许式伟在早年离开盛大创新院。创办七牛云的时候，选择了 Go 这门还未发布正式版的语言。因为小众，许式伟开始有意识地培养 Go 中国社区。

他们做了很多工作。具体有：

- 2012 年 2 月，许式伟首次在公开场合说：Go 会超过 C、Java，成为最流行的语言。讲得最多的一个 PPT 是《Go，Next C》这篇。
- 2012 年 8 月，正式出版 Go 图书，书名为《Go 语言编程》。
- 2020 年下半年，正式对 Go+ 进行了宣传和推广，对大数据科学的领域进行了增强。

## 神秘的技术社区

虽然许式伟已经是七牛云 CEO，但依然在技术领域和咱们的 Go 领域发光发热，并没有因此而停下脚步。许式伟早在 2007 年就成立了一个技术社区。

![](https://image.eddycjy.com/f04e24b25f48c3d2293e64390d22888f.jpeg)

这个社区名字叫 ECUG，ECUG 全称为 Effective Cloud User Group（实效云计算用户组）。

其成立于 2007 年的 CN Erlounge II，由许式伟发起，是科技领域不可或缺的高端前沿团体。作为行业技术进步的一扇窗口，ECUG 汇聚众多技术人，关注当下热点技术与尖端实践，共同引领行业技术的变革。

![](https://image.eddycjy.com/1cba758a30621c7b4db7c92ae9e739d0.jpeg)

截止到 2020 年 ECUG Con 已成功举办了 13 届，ECUG Con 的技术主题主要涉及：云计算、数据、区块链方向。

**今年第 14 届 ECUG 大会将于 2021 年 1 月 16 - 17 日在上海举行，为期两天**。作为 Gopher，身处云原生时代，这样的盛宴不容错过。

购票地址：

![](https://image.eddycjy.com/017bf73c7eaa90dc99d793324b347e88.png)

大会议程如下：

![](https://image.eddycjy.com/1b3475f904becad56e9450aff88d9402.jpg)

大会嘉宾：

![](https://image.eddycjy.com/177b353f31903dcde292755a84af5e73.png)

## 各种福利

这次大会煎鱼**为大家申请到了 15 个免费名额，我会从留言者中随机选 15 位送出**。


同时本次大会还有技术嘉年华的环节，会送出各种礼品：

![](https://image.eddycjy.com/da791fb34cb3a8bbd353bb9171b8c180.jpeg)

有兴趣的鱼粉们赶紧留言，报名参加 ECUG 吧！

================================================
FILE: content/posts/2021giac.md
================================================
---
title: "我周末参加了个架构师大会！"
date: 2021-12-31T12:54:57+08:00
toc: true
images:
tags: 
  - giac
---

大家好，我是煎鱼。

前两天 GIAC 全球互联网架构大会在深圳举办了，总算是有个长年在深圳举办的大会了，愉快参加了大部分的场次，面基了不少社区网友。

分享一些我听了觉得有意义的记录给大家。希望能和大家一起学习进步。本文分别涉及如下几个议题：
- 《hits for microservices desgin》
- 《在企业中的个人成长》
- 《大规模任务调度在 AfterShip 的高可用实践》
- 《快手前端实时性能监控和稳定性度量》
- 《快手中间件 mesh 化实践》

## hits for microservices desgin

一开始先介绍了为什么叫 ”hits“。叫 ”hits“ 的主要原因，是**业务架构没有技术架构那么明确，没有明确的对与错，是个人的工作经验和总结**。

### 微服务解决什么问题

业内常常说到，微服务，微服务。总归期望微服务解决什么问题。

演讲的作者做了如下的调研：

![](https://files.mdnice.com/user/3610/903dfcbb-a0b6-481f-a40e-3476b8ac8b64.png)

从调研结果来看，占比最大的就是 ”独立自治，只关注自己的模块“。这和绝大部分既有业务的公司做微服务的初衷一致。

许多就是被单体的巨石应用折腾的不行，纷纷希望通过拆分微服务来实现业务模块的独立自治。

### 微服务的现状

主要是播放了动图，配合口述。现在大多数服务拆分后的现状，很多就是**改哪影响哪完全不清楚，和水管漏水似的**：

![](https://files.mdnice.com/user/3610/f871b4de-c8b6-47b4-a5e7-5b9f64b73aea.jpg)

(自行脑补一拧水管，堵哪，别的地方就漏)


### 衡量微服务拆分的标准

理想中的微服务拆分，希望要有灵活的组装能力。但拆分后遇到的新问题，实际的情况，拆分后与期望的不一样，拆着拆着就变成了一大坨，但只是说隔开了，与现在企业中微服务运行的现状很贴合。

拆分后如有如下几个痛点：

![](https://files.mdnice.com/user/3610/0890ca8a-4fa1-4173-8334-92a167a47a19.png)

举了几个案例。分别是：
- 订单的例子。
- 报价的系统。
- 数仓的例子。

#### 订单

举的是订单的例子，订单团队非常忙，因为信息都存在订单里，系统其他有任何业务上的变更诉求，都要找订单的团队。

为此，在拆分上需要优化成订单业务只保存订单 ID：

![](https://files.mdnice.com/user/3610/24a64dd9-98ae-419f-afef-aa125513dbd2.png)

各系统存订单ID，各团队自治，实现业务解耦，订单团队就不用因其他业务变更天天加班了。


#### 报价

举的是报价的系统，要是报价团队，针对各个子业务项都要自己实现一般，会非常的辛苦，经常要加班。

我们只需要在报价系统提供接口标准，各系统自己实现，再对接：

![](https://files.mdnice.com/user/3610/92f5b5eb-e5de-4bfd-bab6-f3e9ab2d7a6d.png)

报价团队就不需要每次都重新开会，再对接。报价系统自己只做业务流程的编排，瞬间变轻松了。

#### 数仓

举的是数仓的例子，业务改一个字段，数仓系统要改一个月，否则就会出现问题，因此要求业务有任何 schema 改变都必须要通知数仓团队：

![](https://files.mdnice.com/user/3610/b1a09935-9663-449a-8646-b55ef3e08b7c.png)

很现实的是，基本通知不过来，所以很多公司把他作为绩效，定期考核，出问题定期批评。

建议的是：通过 RPC 的方式提供维护，把数据维护交给业务团队自己维护，数仓团队应该只做具体的跨团队的数据互联。

#### 好的标准的定义

分层，都可以独立变更，可以自己搞自己，只需要保证这一层提供的能力是稳定的就好（全部改一遍的另当别论），不需要了解上下游，只需要维护好 interface。

具体几点：
- 不同模块间完全没影响
- 只共享不可变数据
- 共享可变数据，但接口不变。
- 大部分情况变化的是实现，变化的不是接口，接口的变更次数很少。

参照乐高，关注接口的稳定性，而不是拆的越细越好。

评价的标准是：看不同系统不同模块的互相影响程度，就知道各系统怎么样了。

### 小结

1. 不要在一开始就使用有意义的名词，例如：交易中心，支付中心。大家会根据名字来设计的架构，建议最后再起名字。
2. 复用不是目的，是手段。例如业务中台真的是复用吗，不是。只是互联互通。
3. 好的架构，是要控制复杂度，在一定的规范下尽量自治。
4. 先划分清楚业务模块，划分清楚了，再去设计你的技术架构。

提问时也有涉及到 ”分布式事务“，这简直就是微服务相关议题的必问话题。演讲者表示：倾向持续交付。尽可能不让他有分布式事务。

## 在企业中的个人成长

毛老师的演讲，据说全场综合评分最高，内容是分享了自己在企业成长的三个阶段：
- 阶段一：加入 Startup 公司。
- 阶段二：轮岗。
- 阶段三：重新出发。

分享比较有明确的时间线，我是直接按点来记录的，刚好十条，非常经典。

### 十条纲要

1. 15 年，也不知道什么是 B 站，也找不到人。从以前认识的一些熟人，从别的公司挖回来。**小公司，亲自带。自己熟悉业务，请教老员工文化**。

2. 团队到 40~50 就要考虑做人才梯队了。要保证每个月有 1v1 的简单聊一聊，或是每天现场聊聊。**稳定性问题和管理有关系**，有没有研发红线，例如发布变更，生产无小事。

3. 改变一个人性格非常困难，只能告诉他，给一两次机会。**不合适就放弃，心慈刀快，尽快解决掉**。合适的人，给过两三次机会，自己早就转变过来了，两三次还不行，肯定是难以改变的了。

4. 要做核心的事情，不要什么需要都做。**不要用技术实现去挑战老板的战略考虑，要用业务**。

5. 不要害怕空降，**引入新的人，有竞争压力，有进步**，要做减法，聚焦最重要的事情。向他们学习，看他们的优势，择机成长。

6. 要换位思考，站在平台方，成就业务。**最好的团建是一起拿成果**。从老板的角度考虑，绝对能折腾，绝对能将就，就像基础架构部门，有时候要业务优先。

7. 影响力，技术辐射范围足够广，不同团队落地，自然而然就有了影响力。公司外的影响力，多分享，多参加 meetup。

8. 哪里有需要就去哪里。

9. OKR 要足够的透明，足够的明确。下级要知道，要清楚，甚至是自下而上的 OKR。

10. **团队的会模仿你，看别人的缺点，修正自己**。自己在团队中要做榜样（举例：早点下班的问题）。

### 小结

在职业生涯发展上的小伙伴，建议可以看看毛老师的分享 PPT，看看大佬从 0 到千亿万身家的个人成长发展史。

就如总结所说的：”当你很忙碌的时候，你的管理工作一定出了问题“，值得思考。

## 大规模任务调度在 AfterShip 的高可用实践

初始的业务需求是有优先级调度的需求，用户的调度比物流包裹的优先级高。

任务调度的量比较大，要能运行千万级的优先级任务调度。

### 老版本

老版本是根据 15 分钟划分一个 Topic，可以理解为分区，一天 96 个。

采取的是轮询策略，还没执行的放进延迟队列。实现了 15 分钟粒度级别的任务级别(没法做到 1 分钟，5分钟的这类纬度)。

![](https://files.mdnice.com/user/3610/d78359d3-5c59-4535-a0ed-2214ade04302.png)

存在以下问题：
- 会导致出现波峰，资源浪费。
- 设计过于复杂，导致系统脆弱。
- 链路过长，定位困难。
- 错误的 FIFO 实现。

### 新版本

![](https://files.mdnice.com/user/3610/36b6fce2-c23a-451a-a538-4df3cac19be5.png)

解决思路: 
- 通过 LMSTFY 任务队列，解决延迟和优先级功能，解耦业务。
- 基于 Redis，正在做二级存储，冷热数据隔离。
- 通过指定多个队列，来实现多个优先级调度。取多个队列，A队列有内容，则优先消费A。
- 通过实现接口来队列多个数据存储。
- 借助组件的特性和系统优化，简化了架构。

### 小结

相当于是看了一个任务调度系统的设计发展史，理论上设计的存储和方案不一定得选 Redis 或是 LMSTFY。

不过考虑到演讲者的背景，因此趋向了这个技术方案，也可以从中看到后续任务调度系统规模更大后，可能出现的问题。

## 快手前端实时性能监控和稳定性度量

公司内也有类似的系统，与快手的前端 APM 是一模一样的定位，可以借此看看成熟的系统的选型和发展情况。

### 前端的数据

需要有统一性能指标，用一个指标代表:

- 早期：DCL，Onload，来判断前端页面的性能。页面依赖接口数据容易被绕过，长页面不能反映用户真实感知。

- 设想指标的作用：希望获取白屏时间，代表白屏到非白屏的时间。

但发现也无法保证，计算白屏可能会导致客户端崩溃。不能代表页面核心内容的时间：

![](https://files.mdnice.com/user/3610/0afbfd6c-e9ca-4357-8ddb-c45f26f2c1f7.png)

转为目的是拿到主要内容渲染的时间，业内常见用 FMP、LCP：
- FMP（First Meaningful Paint）：没有标准实现，对页面细微变化或于敏感。某一个 DOM 内部有很多个节点，可能会造成误差。
- LCP（Largest Contentful Paint）：页面内最大内容的渲染时间，最大元素不一定是最重要的元素，例如新闻内的图片。并且浏览器的支持率只有 70%（致命），因为快手很多低端机是不支持的。

### 真正要的指标

考虑业务需要的指标是什么，本质上业务的真正内容是**从接口异步获取回来的**。

因此采取了自定义 FMP，API 响应数据渲染到页面后的时间，代表页面的性能：

![](https://files.mdnice.com/user/3610/5a6f62f8-2ef7-4500-b7a5-b47c62d526ba.png)

这个自定义方案要业务自己计算的，会调用提供的统一方法来计算。虽然有一定侵入，但准确性最高，最有效。

主要有以下三种统一度量指标: 
- API 性能/异常。
- 资源性能/异常。
- 脚本异常。

也做了容器的性能数据，例如：webview 的启动时间比较慢。提前缓存，可以大幅度提升性能。

### 小结

大篇幅主要是介绍了前端指标的定义和摸索过程，这是一个平台的基石数据了。

后续的平台能力拓展如下：

- 在排查问题上：他们做了根因定位，分析了许多前端的具体指标，基本达到出现异常 5 分钟内可通知到业务，10 分钟内给出解决方案建议。
- 在大数据量上：动态采样，批量上报，数据上报保障，异常场景兜底（例如：异常上报不上来，会在恢复后上报异常退出了页面，会记录堆栈信息）
- 在性能拓展上，做了性能周报，主动给业务推，便于他们实时的跟踪自己的情况。也做了数据大屏做全局视角的分析。

## 快手中间件 mesh 化实践

分享是介绍中间件相关的 mesh，比较有意思的是定义了目前业内 mesh 的三代阶段，这倒是没怎么听过。

具体的定义如下：

![](https://files.mdnice.com/user/3610/be285750-bacf-42cd-bcdf-12507849b108.png)

快手中间件采取的是：第三代中间件 mesh，轻 sdk 的方式。

### 选型考虑

在以往，重 sdk 下，整体开发维护成本，升级都比较繁琐，代理业务协议的流量。

如果是以 Istio、Linkerd2 为代表，主要是处理常见的通讯协议（例如：HTTP、gRPC 协议），又对中间件 mesh 不大合适。

最终采取的是 mesh 加轻 SDK 的方式：

![](https://files.mdnice.com/user/3610/89749180-c082-4d7e-8072-55ceec5c385d.png)

在此 mesh 的定位是能力下沉，sdk 的定位是标准化的定义。

### 新的挑战

做过微服务，基础设施的小伙伴都知道，要达到 A，将会在 BCD 付出更多，这是常态。

要上 mesh 非常简单，K8s 里几条命令的事。但后面要处理的事，可就是要切切实实的成本了。

主要面临了如下挑战：
- 成本问题：复杂环境下的统一部署与运维。
- 复杂度问题：规模大、性能要求高、策略复杂。
- 落地推广：对业务来说不是强需求。

### 解决方案

针对以上三点，又配套了做了如下解决方案和措施：

1. 统一运维：对自己，网关的运维平台。对业务，定位排查，可观察性的。

2. 规模大问题：对 Enovy 等做了二开。只传输变更的数据、按需获取，解决单实例服务数过多的问题。

3. 性能要求高：协议栈的优化、序列化优化等，做了大量底层的优化。

4. 实施了面向失败设计，SDK fallback，可以 fallback 切换为直连模式。如果是新功能，没有老的，会切换到 Proxy 模式。

### 业务推广

业务推广这点要单独拧出来讲，因为 mesh 一般的直接收益不是业务，是基础设施，对业务不是强需求会遇到：
- 业务对性能，稳定性敏感。
- 业务很难配合人力配合架构升级。
- 对业务侧的收益并不明显。

据闻现在业内大规模落地的只有字节和蚂蚁，且都是有很多背景因素的，和组织上的人有直接关系。

关于业务推广，演讲者也给出了一些建议，例如：稳定性很重要，搭便车，业务共建，选型有明显业务收益等。

### 小结

近几年各家都纷纷出来分享 mesh，其实基本上现状和应用情况都比较清晰了。

像本次快手 mesh 的分享主要是面向中间件（gRPC、Kafka、RocketMQ、ZK、Mongo、Redis、MySQL）等。

但能明显感觉到业务推广的苦恼，以及可预测的运维投入巨大，这也是所有出来分享 mesh 的核心痛点分享。

其余的技术细节，大多通过二开等方案解决了。


================================================
FILE: content/posts/go/117-build.md
================================================
---
title: "时隔 3 年，Go1.17 增强构建约束！"
date: 2021-12-31T12:54:56+08:00
toc: true
images:
tags: 
  - go
  - go1.17
---

大家好，我是煎鱼。

Go1.17rc1 在前几天终于正式发布了：

![](https://files.mdnice.com/user/3610/a9dd1134-e4f8-4d9c-9c3c-2608728ddf69.png)

看到 Go1.17 增加了一个新特性，是面向 Go 构建时的构建约束的增强。认真一看，是一个时隔 3 年的提案了，原本还在 Go2 和 Go1 之间左右摇摆，这下在 6 月底 Russ Cox 就输出了新草案：《Bug-resistant build constraints — Draft Design》。紧接着直接计划在 Go1.17 发布了。

一气呵成，真实版高效能了。

如下图：

![](https://files.mdnice.com/user/3610/10037273-887d-45c0-9eca-6ef36d7c4d72.png)

之前小咸鱼有遇到好几个朋友，在报错时压根不知道 Go 有这个约束语法，以为只是个单纯的注释，直接不明所以然，感觉科普之路任重道远。

今天这篇文章煎鱼就来讲讲构建约束这事。

注：下个月 Go1.17 就会正式发布，距离 Go1.18 泛型出山只差一点点距离了，值得期待！

## 构建约束的背景

简单来讲，在真实环境中，可能需要为不同的编译环境编写不同的 Go 代码，所以需要做构建约束。

划重点，Go 语言对这一问题的解决方案是**在文件层面进行有条件的编译：每个文件要么在编译中，要么不在**。

也就是，假设不符合构建约束的场景。那么会直接不编译这个文件，因为他不在编译范围内。那在程序想运行时就会报错，表示找不到文件。因此有许多的同学看着报错信息，经常找不着北...

## 现有的构建约束

既然是叫 “增强”。说明现有就有构建约束。最早的构建约束是在 2011 年 9 月引入的构建约束。

我们平时常见的构建约束（build constraint），也叫做构建标记（build tag），构建约束必须出现在 `package` 之前。

平时会在 Go 工程的文件中的最开始会看到如下行注解：

```
// +build
```
为了将构建约束与包文档区分开来，构建约束后必须跟一个空行。

```
// +build linux,386 darwin,!cgo
```

又或是：

```
// +build linux darwin
// +build amd64
```

还可以根据 Go 版本来约束：

```
// +build go1.9
```

其主要支持如下几种：
- 指定编译的操作系统，例如：windows、linux 等，对应 `runtime.GOOS` 的值。
- 指定编译的计算机架构，例如：amd64、386，对应 `runtime.GOARCH` 的值。
- 指定使用的编译器，例如：gccgo、gc。
- 指定 Go 版本，例如：go1.9、go1.10 等。
- 指定自定义的标签，例如：编译时通过指定 `-tags` 传入的值。
- ...

## 有什么问题

既要用动他，本着 Go team 的 less is more 原则。想必是现有的构建约束，存在着什么问题，才需要调整他。

### 对语法困惑

从 issues 的反馈来看，是太复杂，如下：

```
// +build linux,386 darwin,!cgo
```

他表达的构建约束是：(linux AND 386) OR (darwin AND (NOT cgo)) 。

感觉可以像三元运算符一样玩出花，可参见《Go 凭什么不支持三元运算符？》，这更夸张，没常见的逻辑符。

也可以更复杂一些：

```
// +build 386 !gccgo,amd64 !gccgo,amd64p32 !gccgo
```

会导致会混淆用户的认知，如果能够这样写更好：

```
// +build 386 amd64 amd64p32
// +build !gccgo
```

### 对布局困惑

现在的 `// +build` 有硬性的使用规则：
- 必须出现在文件顶部附近，前面只能有空行和其他行注释。这些规则意味着在 Go 文件中，构建约束必须出现在 package 子句之前。
- 为了将构建约束与包文档区分开来，一系列构建约束后必须跟一个空行。

像是以下失败案例：

```golang
package main

// +build linux
```

又或是：

```golang
/*
Copyright ...
*/

// +build linux

package main
```

整体来看，官方在 2020 年 3 月对 `// +build` 注解的使用情况进行了分析，得出以下几种常见情况：
- 忽略了`/* */`注释后的构建约束，通常是版权声明。
- 忽略了文档注释中的构建约束。
- 忽略了包声明后的构建约束。

这些都是实际项目中出现的，也就是这个构建约束的布局约束并不好，造成了很多意外和反馈。

像是版权声明的统一写入，基本都是脚本统一打上去的。会造成大量的隐藏版本 BUG。

## 增强后的构建约束

增强，就是优化，主要的目标之一是解决语法、布局困惑。

设计的核心思想：用新的 `//go:build` 取代目前用于构建标签选择的 `//+build`，并且使用更广为熟悉的布尔表达式。

设计的关键：平滑过渡，避免破坏 Go 代码。

以前老的注解：

```
// +build linux
// +build 386
```

新的注解：

```
//go:build linux && 386
```

新的语法主体为 Go spec 的 EBNF 标记：

```
BuildLine      = "//go:build" Expr
Expr           = OrExpr
OrExpr         = AndExpr   { "||" AndExpr }
AndExpr        = UnaryExpr { "&&" UnaryExpr }
UnaryExpr      = "!" UnaryExpr | "(" Expr ")" | tag
tag            = tag_letter { tag_letter }
tag_letter     = unicode_letter | unicode_digit | "_" | "."
```

也就是说，构建标记的语法与其当前形式保持不变，但构建标记的组合现在使用 Go 的 ||、&& 和 ! 运算符和括号完成。

另外一个文件只能有一行构建语句，也就是一个文件有多行 `//go:build` 是错误的，如此设计的目的是为了消除关于多行是隐式 AND 还是 OR 在一起的混淆。

## 过渡阶段

在过渡阶段，也就是 Go1.17 起。官方的 gofmt 工具会自动根据旧语法转换新版的语法，以保证兼容性。

例如：

```
// +build !windows,!plan9
```

会转变为：

```
//go:build !windows && !plan9
// +build !windows,!plan9
```

后面是计划把 `//+build` 给完全下线的。

![](https://files.mdnice.com/user/3610/6fcaf62d-bd78-475b-85f1-614d5bc51437.png)

常规 Go 工程基本用不到，因此就不进一步展开描述了。

对过渡阶段感兴趣的可以看看 《Bug-resistant build constraints — Draft Design》的 Transition 部分，比较长，正常来讲是不需要我们关注的。

## 总结

Go 1.17 构建约束的增强，一下子让整个语法明确了起来。统一为 `//go:build`，至少不会有人看到 `//+build` 又以为是普通注释了。

**你是否有在工作中遇到构建的版本、环境约束等场景呢，欢迎大家在评论区留言交流**！

================================================
FILE: content/posts/go/117-errorstack.md
================================================
---
title: "Go1.17 新特性，优化抛出的错误堆栈"
date: 2021-12-31T12:55:05+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

平时在日常工程中，我们常常会用到异常恐慌（panic）的记录和追踪。最常见的就是，线上 panic 了之后，我们总想从中找到一些蛛丝马迹。

我们很多人是看 panic 是看他的调用堆栈。然后就开始猜，看代码。猜测是不是哪里写的有问题，就想知道 panic 是由什么参数引起的？

因为知道了诱发的参数，排查问题就非常方便了。为此**在 Go1.17，官方对这块的调用堆栈信息展示进行了优化**，使其可读性更友好。

## 案例

结合我们平时所使用的 panic 案例。如下：

```golang
func main() {
	example(make([]string, 1, 2), "煎鱼", 3)
}

//go:noinline
func example(slice []string, str string, i int) error {
	panic("脑子进煎鱼了")
}
```

运行结果：

```
$ go run main.go
panic: 脑子进煎鱼了

goroutine 1 [running]:
main.example(0xc000032758, 0x1, 0x2, 0x1073d11, 0x6, 0x3, 0xc000102058, 0x1013201)
	/Users/eddycjy/go-application/awesomeProject/main.go:9 +0x39
main.main()
	/Users/eddycjy/go-application/awesomeProject/main.go:4 +0x68
exit status 2
```

我们函数的入参是：`[]string、string、int`，核心关注到 `main.example` 方法的调用堆栈信息：

```golang
main.example(
    0xc000032758, 
    0x1, 
    0x2, 
    0x1073d11, 
    0x6, 
    0x3, 
    0xc000102058, 
    0x1013201
)
```
明明只是函数三个参数，却输出了一堆，对应起来非常的不清晰。

其实际对应是：

- slice：0xc000032758、0x1、0x2。
- string：0x1073d11、0x6。
- int：0x3。

这里存在的问题是，看调用堆栈的人，还得必须了解基本数据结构（例如：slice、string、int 等），他才知道每个函数入参他对应拥有几个字段，才能知道其内存布局的结构，有一点麻烦。

并且从程序运行的角度来讲，这么水平平铺的方式，并不直观和准确。因为不同类型他是多个字段组合成结构才能代表一个类型。这不得还要人为估测？

## 优化

终于，这一块的调用堆栈查看在 Go1.17 做了正式的改善。如下：

```golang
$ go1.17 run main.go 
panic: 脑子进煎鱼了

goroutine 1 [running]:
main.example({0x0, 0xc0000001a0, 0xc000034770}, {0x1004319, 0x60}, 0x0)
	/Users/eddycjy/go-application/awesomeProject/main.go:9 +0x27
main.main()
	/Users/eddycjy/go-application/awesomeProject/main.go:4 +0x47
exit status 2
```

新版本的调用堆栈的信息改变：

```golang
main.example(
    {0x0, 0xc0000001a0, 0xc000034770}, 
    {0x1004319, 0x60}, 
    0x0
)
```

在 Go 语言以前的版本中，调用堆栈中的函数参数被打印成基于内存布局的十六进制值的形式，比较难以读取。
 
在 **Go1.17 后，每个函数的参数都会被单独打印，并且以 “，” 隔开**，复合数据类型（例如：结构体、数组、切片等）的参数会用大括号包裹起来，整体更易读。

其实际对应如下：

- slice：0x0, 0xc0000001a0, 0xc000034770。
- string：0x1004319, 0x60。
- int：0x0。

这里也有一块细节要注意，你会发现 Go1.17 的函数参数的数量和以往的版本相比，少了。是因为函数的返回值存在于寄存器中，而不会存储到内存中。

因此函数返回值可能会是不准确的，所以也在新版本中也就不再打印了。

## 总结

在 Go1.17 的新版本中，调用堆栈的函数参数的可读性得到了进一步的优化和调整，在后续的使用上可能能够带来一定的排错效率的提高。

你平时在借助调用堆栈排查问题呢，希望还获得什么辅助呢？

## 参考
- [GoTip: New Stack Trace Output Wrong](https://github.com/golang/go/issues/46708)
- [cmd/compile: bad traceback arguments](https://github.com/golang/go/issues/45728)
- [Go 1.17新特性详解：使用基于寄存器的调用惯例](https://mp.weixin.qq.com/s/AkJoXLlpSmw5vMZDpXoq5w)
- [doc/go1.17: reword "results" in stack trace printing](https://groups.google.com/g/golang-codereviews/c/JkhaLqHFReM?pli=1)

================================================
FILE: content/posts/go/117-generics.md
================================================
---
title: "Go 1.17 支持泛型了？具体怎么用"
date: 2021-12-31T12:55:02+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

千呼万唤的，Go1.17 前几天终于发布了：

![](https://files.mdnice.com/user/3610/45fe4f8a-ef8e-41a0-abba-ecdc05fe61c5.png)

先前我写了几篇 Go1.17 新特性的文章，有兴趣的小伙伴可以看看：

- [一个新细节，Go 1.17 将允许切片转换为数组指针！](https://mp.weixin.qq.com/s/v1czjzlUsaSQTpAOG9Ub3w)
- [我要提高 Go 程序健壮性，Fuzzing 来了！](https://mp.weixin.qq.com/s/zdsrmlwVR0bP1Q_Xg_VlpQ)
- [提了 3 年，Go1.17 终于增强构建约束！](https://mp.weixin.qq.com/s/5kLFIuI0UJl_o8vMmZNfoA)

今天的主题是泛型，众所皆知 Go1.18 泛型就会正式释出，都很期待，毕竟大更新，所有配套都会陆续有来！
其实，**在 Go1.17 的此刻其实可以使用泛型了**，泛型代码已合入 master 分支。

咱们只需要一点点操作，就能提前过上 Go 泛型的实验生活了。

## 升级 Go1.17 

你需要先升级 Go1.17，如下图：

![](https://files.mdnice.com/user/3610/a3260cf0-f9bc-4c86-aafd-4d08480143b9.png)

安装后查看版本信息是否正常输出：

```
go1.17 version
go version go1.17 darwin/amd64
```

## 使用泛型

接着写入一个基本的泛型 Demo：

```golang
import (
	"fmt"
)

func Print[T any](s []T) {
	for _, v := range s {
		fmt.Print(v)
	}
}

func main() {
	Print([]string{"你好, ", "脑子进了煎鱼\n"})
	Print([]int64{1, 2, 3})
}
```

只需要在 run 和 build 的命令执行时指定 `-G` 标识就好了。不过有的小伙伴可能会疑惑，为什么要这么干？

其实这类提前放入主版本的操作，在 Go 语言中并不少见。像是现在所见的 `GO111MODULE`，早期的 `GO15VENDOREXPERIMENT` 都有些这么个味道。都是逐步入场，分阶段使用，等确定成熟、完善后再渐渐去掉。

本次泛型也采取了这种方法，按照提案，目前使用的是 `-G` 标识做为泛型的开关。

运行的命令如下：

```
go1.17 run -gcflags=-G=3 xxx
``` 

就可以运行带有泛型的代码。

查看输出结果：

```
$ go1.17 run -gcflags=-G=3 generics.go
# command-line-arguments
./generics.go:7:6: internal compiler error: Cannot export a generic function (yet): Print

Please file a bug report including a short program that triggers the error.
https://golang.org/issue/new
```

竟然报错了，煎鱼你翻车了是吧...

根据错误提示可得知，是还没实现导出一个通用函数的功能。那样我们只需要把 `Print` 方法改为 `print`，再执行就可以了。

再次执行后的输出结果：

```
你好, 脑子进了煎鱼
123
```
成功输出了不同类型的值。

## 更多的案例

在 GitHub 有个小伙伴 mattn 整理了完整的泛型使用案例后开源了，可以实际下载使用看看：

![github.com/mattn/go-generics-example](https://files.mdnice.com/user/3610/a3e768b4-ca68-448d-b4b8-98a3fce447da.png)

大家根据上面的介绍来实际使用就可以达到运行泛型的效果了，GitHub 地址是：github.com/mattn/go-generics-example。

## 总结

经过多年的折腾，Go 语言在发布的 1.17 版本中已经包含了泛型的功能。将会在 Go1.18 正式宣发泛型，我们将会是Go 历史新阶段的见证者。

为什么？因为随着 Go1.18 的逼近，我们将会将会见到越来越多的新工具支持和变更，甚至会改变不少 Go 工程的写法。

欢迎大家在评论区分享你的看法！

================================================
FILE: content/posts/go/117-module-pruning-lazy.md
================================================
---
title: "Go1.17 新特性：对 Go 依赖管理的一把大剪刀"
date: 2021-12-31T12:55:03+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

不得不说。我可是个经历过 Go 依赖管理群魔乱舞，Go modules 迁移一堆 BUG 的人儿，难顶...
为此当年我写了不少技术文章，希望给大家避坑。

如下：
- [Go Modules 终极入门](https://mp.weixin.qq.com/s/6gJkSyGAFR0v6kow2uVklA)
- [干货满满的 Go Modules 知识分享](https://mp.weixin.qq.com/s/uUNTH06_s6yzy5urtjPMsg)
- [Go1.16 新特性：Go mod 的后悔药，仅需这一招](https://mp.weixin.qq.com/s/0g89yj9sc1oIz9kS9ZIAEA)

在近期 Go1.17 发布后，Go modules 带来了两大更新，煎鱼摩拳擦掌，他们分别是：
- 模块依赖图裁剪（module graph pruning）
- 延时模块加载（lazy module loading）

今天带大家一起来了解这两块内容，争取了解其为何物，背景又是什么。

## 背景

在日常的 Go 工程开发中，不知道你有没有遇到过 Go modules 的一个奇怪的点。大家没说，就以为是正确的，默认就接受了。

引用官方的 [mod_lazy_new_import.txt](https://github.com/golang/go/blob/4012fea822763ef3aa66dd949fa95b9f8d89450a/src/cmd/go/testdata/script/mod_lazy_new_import.txt "mod_lazy_new_import.txt") 的案例来说，就是假设我们在代码中：
- main module 是 lazy。其导入了 module A 的 package x，package x 又导入了 module B。
- main module lazy 也相当于同时导入了 module A 的 package y。
- module A 的 package y 又导入了 module C 的 package z。

关联如下图所示：

![module 关联图示](https://image.eddycjy.com/d535e2d41648a346c08c41ac38eff6b9.jpg)

这个 Go 程序如果运行起来，会发生什么情况呢？**在 Go1.17 以前，如果你不存在 module C 的 package z**，程序在编译构建的时候就会报错，提示找不到。

实际上 module C 的 package z 并没有**对你主程序有任何建设意义**，俗话来讲就是 “占着茅坑不拉屎”。

他只是因为 main module 在导入 module A 时，也被 “间接” 导入了 package y 的依赖，也就是我们常看到的 go.mod 文件中的 “indirect” 标识，他们会导致构建失败，让人直呼无奈。

## Go1.17 module 改进

显然，社区反馈希望避免看到 “不相关” 的传递依赖等，也因此有了 Go1.17 的 module 改造。

![](https://files.mdnice.com/user/3610/e69f5155-3334-462f-b021-bee477c62c49.png)

接下来的 module 例子我们将会结合提案 [《Proposal: Lazy Module Loading》](https://go.googlesource.com/proposal/+/master/design/36460-lazy-module-loading.md "Proposal: Lazy Module Loading") 、[《cmd/go: module graph pruning and lazy module loading》](https://github.com/golang/go/issues/36460 "cmd/go: module graph pruning and lazy module loading") 以及 《[Module graph pruning](https://golang.google.cn/ref/mod#graph-pruning "Module graph pruning")》的内容、案例来进行说明和介绍。

### module graph pruning

第一个改进就是模块依赖图裁剪（module graph pruning），这是这个版本 module 优化的基础。

在 Go1.17 以前，只要该项目的 go.mod 文件分析出来你存在间接的依赖，如果你没有安装过该依赖，就会出现报错。

错误提示如下：

```golang
$ go build
go: example.com/a@v0.1.0 requires
 example.com/c@v0.1.0: missing go.sum entry; to add it:
 go mod download example.com/c
```

这个时候我们都会默默地去安装一遍...没想过这是间接依赖，和我们的程序没一点直接的代码关系。

在 Go1.17 及之后就变了，go.mod 文件如下，会存在 2 块 require 代码块：

```golang
module example.com/lazy

go 1.17

require example.com/a v0.1.0

require example.com/b v0.1.0 // indirect
...
```

这就是区别，第一块的 require 我们眼熟，那分拆出来的第二块 require 的是什么呢？

这就是那些模块的间接依赖（常见到的 indirect 标识依赖）。可以理解为像是其他语言的 xxx.lock 文件一样的存在。

此处分析出来的间接依赖，将会不会像以前一样阻碍编译构建，只会真正有使用到的才会进行识别。

### lazy module loading

第二个改进是延时模块加载（lazy module loading），是基于模块依赖图裁剪（module graph pruning）的场景上的进一步优化。

也就是以往那些没被使用到的，但又间接依赖的模块。在 Go1.17 及以后不会被 Go 命令读取和加载，只有真正需要的时候才会加载。

### 副作用

Go module 依赖图裁剪也带来了一个副作用，那就是 go.mod 文件 size 会变大。

在 Go 1.17 版本之后，每次 go mod tidy（当go.mod中的go版本为1.17时），Go 命令都会对 main module 的依赖做一次深度扫描（deepening scan）。

该操作将 main module 的所有直接和间接依赖都记录在 go.mod 中，考虑到内容较多，Go 1.17 将直接依赖和间接依赖分别放在两个不同的 require 代码块中。

也就是上文所见到的内容。

## 总结

自从 Go 语言推出 Go modules 依赖，module 一直不断地在优化和改进。虽然看上去已经越来越好用了，但依然似乎存在不少问题。

就拿本次变更来讲，我也是在好朋友的 Go 微信群中看到提问，才思考了起来。因为大家看到第二块 require 时，虽然知道是间接依赖的包，但更明确，为什么要单独出来？

大家其实是不大理解的，本次变更也可能存在语义不清，不够明确的情况。但无论如何，后续我们可以继续观察。

================================================
FILE: content/posts/go/117-performance.md
================================================
---
title: "Go1.17 新特性，凭什么提速 5~10%？"
date: 2021-12-31T12:55:04+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在 Go1.17 发布后，我们惊喜的发现 Go 语言他又又又优化了，编译器改进后产生了约 5% 的性能提升，也没有什么破坏性修改，保证了向前兼容。

![](https://files.mdnice.com/user/3610/c39ffb33-4afd-4537-a172-4919be7975a4.png)

他做了些什么呢，好像没怎么看到有人提起。为此今天煎鱼带大家来解读两新提案：
- 《[Proposal: Register-based Go calling convention](https://go.googlesource.com/proposal/+/master/design/40724-register-calling.md "Proposal: Register-based Go calling convention")》
- 《[Proposal: Create an undefined internal calling convention](https://go.googlesource.com/proposal/+/master/design/27539-internal-abi.md "Proposal: Create an undefined internal calling convention")》

本文会基于提案讲解和拆解，毕竟分享新知识肯定要从官方资料作为事实基准出发。

## 背景

在以往的 Go 版本中，Go 的调用约定简单且几乎跨平台通用，其原因在于选用了基于 Plan9 ABI 的堆栈调用约定，也就是**函数的参数和返回值都是通过堆栈上来进行传递**。

这里我们一共提到了 Plan9 和 ABI，这是两个很关键的理念：
- Plan9：Go 语言所使用的汇编器，Rob Pike 是贝尔实验室的猛人。
- ABI：Application Binary Interface（应用程序二进制接口），ABI 包含了应用程序在操作系统下运行时必须遵守的编程约定（例如：二进制接口）。

该方案的优缺点如下：
- 优点：实现简单，简化了实现成本。
- 缺点：性能方面付出了不少的代价。

按我理解，在 Go 语言初创时期，采取先简单实现，跑起来再说。也合理，性能倒不是一个 TOP1 需求。

## Go1.17 优化

### 什么是调用惯例

在新版本的优化中，提到了调用惯例（calling convention）的概念，指的是**调用方和被调用方对函数调用的共识约定**。

这些共识包含：函数的参数、返回值、参数传递顺序、传递方式等。

双方都必须遵循这个约定时，程序的函数才能正常的运行起来。如果不遵循，那么该函数是没法运行起来的。

### 优化是什么

在 Go1.17 起，正式将把 Go 内部 ABI 规范（在 Go 函数之间使用）从基于堆栈的函数参数和结果传递的方式**改为基于寄存器的函数参数和结果传递**。

本次修改涉及到的项非常多，该优化是持续的，原本预计是 Go1.16 实现，不过拖到了 Go1.17。

![](https://files.mdnice.com/user/3610/41e7a047-cac2-4b8a-9006-762fd73ee2a4.png)

目前实现了 amd64 和 arm64 架构的支持。还有不少的更多的支持会持续在 Go1.18 中完成，具体进度可见 [issues #40724](https://github.com/golang/go/issues/40724 "issues #40724")。

### 性能如何

在 [Go1.17 Release Notes](https://golang.org/doc/go1.17 "Go1.17 Release Notes") 中明确指出，用一组有代表性的 Go 包和程序的基准测试。

官方数据显示：
- Go 程序的运行性能提高了约 5%。
- Go 所编译出的二进制大小的减少约 2%。

在民间数据来看，在 [twitter](https://twitter.com/__Achille__/status/1431014148800802819 "twitter") 看到 @Achille 表示从 Go1.15.7 升级到 Go1.17 后显示。在一个大规模的数据处理系统上进行的 Go1.17 升级产生了惊人的效果，我们来看看他的真实数据。

CPU、Malloc 调用时间减少了约15%：

![图来自 @Achille](https://files.mdnice.com/user/3610/0c98d5c9-4691-4c39-92af-fe25fd41de25.png)


![图来自 @Achille](https://files.mdnice.com/user/3610/2ea79a65-297f-49aa-a97f-15d02dbf5c9b.png)


RSS 大小更接近于堆的大小：

![图来自 @Achille](https://files.mdnice.com/user/3610/14b1886f-7bd7-4ea2-9967-5272f5b09c79.png)

从原本的 1.6GB 降至 1GB。

结合官方和民间数据来看，优化效果是明确且有效的。有兴趣的小伙伴也可以自己测一测。

## 总结

在 Go1.17 这一个新版本中，只需要简单的升一升 Go 版本，我们就能得到一定的性能优化，这是非常不错的。

从以往的基于堆栈的函数参数和结果传递的方式改为 Go1.17~Go1.18 基于寄存器的函数参数和结果传递，Go 语言正在一步步走的更好！

你觉得呢？

================================================
FILE: content/posts/go/118-build-info.md
================================================
---
title: "Go1.18 新特性：编译后的二进制文件，将包含更多信息"
date: 2022-02-05T16:02:45+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

我有一个朋友，，开开心心入职，想着施展拳脚，第一个任务就是对老旧的二进制文件进行研究。

他一看，这文件，不知道是编译器用什么参数怎么打出来的，环境不知道是什么，更不知道来自什么代码分支？

这除了是项目流程上的问题外，Go 在这块也有类似的小问题，处理起来比较麻烦。

## 背景

日常中很难从 Go 二进制文件中检索元信息，要么是信息完全缺失，要么提取需要对二进制文件进行大量解析。

包含的元信息如下：

|  元信息   | 提取处  |
|  ----  | ----  |
| Go 构建版本  | 符号表，通过全局变量 `runtime.buildVersion` 来获取 |
| 构建信息，例如：模块和版本 | 符号表，通过全局变量 `runtime/debug.modinfo` 来获取 |
| 编译器选项，例如：构建模式、编译器、gcflags、ldflags 等 | 无法获取 |
| 用户定义的自定义数据，例如：应用程序版本等 | 需在编译时设置全局字符串变量，才可以获取 |

关注到编译器选项，也就是参数等都是无法得知的，也就是会提高获取如何编译出来的难度。

## 新提案

Michael Obermüller 提出了一个新的提案《[cmd/go: add compiler flags, relevant env vars to 'go version -m' output](https://github.com/golang/go/issues/35667)》用于解决上述问题。

在提案中想要的是 JSON 格式的结构输出：

```json
{
    "version": "go1.13.4",
    "compileropts": {
        "compiler": "gc",
        "mode": "pie",
        "os": "linux",
        ...
    },
    "buildinfo": {
        "path": "脑子进煎鱼了",
        "main": {
            "path": "HelloWorld",
            "version": "(devel)",
        },
        "deps": []
    },
    "user": {
        "customkey": "customval",
        ...
    }
}
```

Russ Cox 表示由于编译信息已有既有格式，并且默认使用 JSON 只会让二进制文件变得更大。好处少，没必要，改为了选项化的支持。

新的 Go1.18 版本中，可以通过既有的：

```
go version -m
``` 

查看到提案所提到的信息。

例如：

```go
$ gotip version
go version devel go1.18-eba0e866fa Mon Oct 18 22:56:07 2021 +0000 darwin/amd64
$ gotip build ./
$ gotip version -m ko
...
	build	compiler	gc
	build	tags	goexperiment.regabiwrappers,goexperiment.regabireflect,goexperiment.regabiargs
	build	CGO_ENABLED	true
	build	CGO_CPPFLAGS	
	build	CGO_CFLAGS	
	build	CGO_CXXFLAGS	
	build	CGO_LDFLAGS	
	build	gitrevision	6447264ff8b5d48aff64000f81bb0847aefc7bac
	build	gituncommitted	true
```

若需要输出 JSON 格式，也可以通过指定 `go version -json` 达到一样的效果。

在上面的输出中，现有的编译器选项等都会包含在内，能够让大家对整体编译后的二进制文件溯源有一个更好的认知。

## 总结

在今天这篇文章中，给大家介绍了 Go1.18 的一个新的变化。

新版本中，编译器选项/参数、相关环境变量等，将会包含在编译后的二进制文件中，能够更便于后人排查和查看信息。

================================================
FILE: content/posts/go/118-build.md
================================================
---
title: "泛型是双刃剑？Go1.18 编译会慢近 20%"
date: 2021-12-31T12:55:18+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

目前 Go 的泛型已经在稳定推进的过程，在 Go1.18 将会释出正式的第一版。不过前两天我看到 @danscales 提出的《cmd/compile: Go 1.18 compile time may be about 18% slower than Go.17 (largely from changes due to generics)》。

作者表示在 Go1.18 有了泛型后，编译速度将会变慢，虽然不意外，说明副作用还是有的，升级需谨慎。

以下为修整后概括的原文信息。

## 性能分析

这个测试主要是测试 Go 泛型对 Go 编译器带来的影响，并没有输入大量的测试用例，是最简单的比较，仅代表大部分的差异。

比较的内容是 Go 泛型的 -G=0 和 -G=3 模式下的编译时间。

分别代表以下含义：
- -G=0 模式：默认不打开泛型的模式。
- -G=3 模式：打开泛型的模式。

Go 1.18 中的 -G=0 模式和 Go 1.17 模式的比较显示，由于非泛型的变化，编译器的速度可能降低了~1%（因为 -G=0 模式不支持泛型）。

Go 1.18 的编译时间可能比 Go 1.17 慢 15-18%，这主要是由于实现泛型所带来的变化，也就是 Go1.18 开启泛型下，编译时间会变慢。

## 差异在哪

大部分的差异是由于新的编译器前端处理，因为 SSA 后端对于泛型完全没有变化。

- 在 -G=0 模式下（用于 Go 1.18 之前的所有编译器）：有一个语法分析器，创建 ir.Node 节点树的 noder 阶段，以及标准类型检查器。
- 在 -G=3 模式下：有相同的语法分析器，但程序首先由 types2（支持泛型）进行类型检查。

在通过 -G=3 模式打开泛型后，会有一个 noder2 阶段，使用语法信息和 types2 类型检查器的类型信息创建 ir.Node 节点树。在一次运行中，noder+ types1-typechecking 的开销总和约为 4%，而 types2-typechecker+noder2 的总和为 14%。

可以看到大部分的速度下降是由于改变了编译前端处理（并不意外）。

## 总结

可以明确的是，在打开泛型后，Go1.18 编译时间可能会慢 15-18%，Go 官方将计划在 Go 1.19 中减少这种额外的开销。

泛型的双刃剑初见，后续不管是编译时间、执行时间（预计不会减缓）、泛型的滥用、最佳实践等，都值得我们去讨论和关注。

欢迎大家在评论区讨论和交流：）

================================================
FILE: content/posts/go/118-constraints.md
================================================
---
title: "Go 新语法挺丑？最新的泛型类型约束介绍"
date: 2021-12-31T12:55:19+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

近期我们在分享《[3 件与 Go 开发者有关的大小事](https://mp.weixin.qq.com/s/22TeQOUjf_glPX3QLPX8yw)》时，里面有一部分有提到 Go 泛型的约束类型语法又又又变了。

在评论区里看到不少的读者朋友大呼泛型的新类型约束语法挺丑，不如原本的好...

如下：

![](https://files.mdnice.com/user/3610/8e734a8f-612c-41c3-a0cd-8a5fe6eea483.png)

为此，今天煎鱼就带大家来看看，为什么会发生泛型的新语法会这种改变？

## 问题背景

原本 @Ian Lance Taylor 设计的的泛型类型关键字如下：

```golang
type T interface {
 type int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, uintptr, float32, float64, complex64, complex128, string
}
```
看起来好像非常 “顺眼”。但在《[proposal: Go 2: sum types using interface type lists](https://github.com/golang/go/issues/41716 "proposal: Go 2: sum types using interface type lists")》中社区进行了热烈的讨论。

认为该类型约束的关键字，过于 “模棱两可”。像是 @Damien Neil 所提出的以下两个例子。

结构体的例子：

```golang
package p
type mustIncludeDefaultCase struct{}
type MySum interface {
  type int, float64, mustIncludeDefaultCase
}
```

不明确的点之一，如果类型列表包含一个未导出的类型，那又应该是如何处理呢？

接口的例子：

```golang
type T interface { type int16, int32 }
func main() {
  var x T
  switch x.(type) {
  case int16:
  case int32:
  } 
}
```

你认为程序会跑进哪个 switch-case 的代码块里呢，是 int16，还是 int32？

不，都不会，变量 x 是 nil，如此迷惑。

在社区讨论中，发现设计与真实场景一结合，发现这个类型规则在普通的接口类型、在约束中使用也太微妙了。

用类型列表嵌入接口时的行为也很奇怪。认为可以做的更好，那就是 “更显式”。

## 新提案

为此，Go 泛型的设计者 @Ian Lance Taylor 提出了一个新的提案《[spec: generics: use type sets to remove type keyword in constraints](https://github.com/golang/go/issues/45346 "spec: generics: use type sets to remove type keyword in constraints")》。

其包含三个新的、更简单的想法来取代泛型提案中定义的类型列表。

### 关键名词

新语法在泛型处增加一个新概念：接口元素（interface elements），用作约束条件的接口类型，或者被嵌入约束条件的接口类型，允许嵌入一些额外的构造。

被嵌入的可以是：
- 任何类型，而不仅仅是一个接口类型。
- 一个新的句法结构，称为近似元素。
- 一个新的句法结构，称为联合元素。

重点名词，我们继续展开讲解，分别是：
- 嵌入约束。
- 近似元素。
- 联合元素。
- 接口类型。

### 联合元素

原先的语法中，类型约束会用逗号分隔的方式来展示。

如下：
```golang
type int, int8, int16, int32, int64
``` 

在新语法中，结合定义为 union element（联合元素），写成一系列由竖线 ”|“ 分隔的类型或近似元素。

如下：

```golang
type PredeclaredSignedInteger interface {
	int | int8 | int16 | int32 | int64
}
```

常常会和下面讲到的近似元素一起使用。

### 近似元素

新语法，他的标识符是 “~”，完整用法是 `~T`。`~T` 是指底层类型为 T 的所有类型的集合。例如：

```golang
type AnyInt interface{ ~int }
```

他的类型集是 `~int`，也就是所有类型为 int 的类型（如：int、int8、int16、int32、int64）都能够满足这个类型约束的条件。

再结合以上的分隔来使用，用法为：

```golang
type SignedInteger interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64
}
```

相当于泛型提案中使用的以下类型：

```golang
interface {
	type int, int8, int16, int32, int64
}
```

新语法只需借助近似标识符 `~int` 来表达就可以了，更明确的表示了近似匹配，而不是存在隐式理解。

### 嵌入约束

一个类型约束可以嵌入另一个约束，联合元素可以包括约束。

例如：

```golang
// Signed is a constraint whose type set is any signed integer type.
type Signed interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64
}

// Unsigned is a constraint whose type set is any unsigned integer type.
type Unsigned interface {
	~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr
}

// Float is a constraint whose type set is any floating point type.
type Float interface {
	~float32 | ~float64
}

// Ordered is a constraint whose type set is any ordered type.
// That is, any type that supports the < operator.
type Ordered interface {
	Signed | Unsigned | Float | ~string
}
```

这个很好理解，就是正式支持嵌入约束了。

### 接口类型（联合约束元素）

在联合元素中，使用接口类型的话。将会把该类型集添加到联合中。

例如：

```golang
type Stringish interface {
	string | fmt.Stringer
}
```

Stringish 的类型集将是字符串类型和所有实现 `fmt.Stringer` 的类型，任何这些类型（包括 `fmt.Stringer` 本身）将被允许作为这个约束的类型参数。
 
也就是针对接口类型做了特殊的处理。

## 总结

今天这篇文章，主要讲解了 Go 泛型的新语法，其实本质上还是为了解决引入 A 后，出现了 BCD 新问题，又继续引入新的语法和模式来解决。

整体就是三个观点：

- 显式匹配：使用**明确的 "~" 近似元素，澄清了何时在底层类型上进行匹配**。
- 明确含义：**使用 “|” 而不是 “,” 强调这是一个元素的联合**。
- 嵌套优化：通过允许约束嵌入非界面元素，类型关键字可以被省略。

这就是用这两个新语法符号的原因，被嫌丑的新语法标识符 “|” 和 “~” ，其实也是在 issues 的大范围讨论中，由社区贡献出来的。

算是有利有弊？**你的看法如何，欢迎在评论区留言**：）


================================================
FILE: content/posts/go/118-cut.md
================================================
---
title: "Go1.18 新特性：新增好用的 Cut 方法"
date: 2022-02-05T16:03:31+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在各种写业务代码的时候，大家会常常要处理字符串的内容。常见的像是用邮箱登陆账号，如果是：eddycjy@gmail.com，那就得根据 @ 来切割，分别取出前和后，来识别用户名和邮箱地址。

这种需求，在 Go 里写起来方便吗？今天就由煎鱼带大家了解。

## 背景

### 重复代码

无独有偶，Ainar Garipov 在许多项目中遇到了前面我们所提的切割需求。

例如：

```go
idx = strings.Index(username, "@")
if idx != -1 {
  name = username[:idx]
} else {
  name = username
}  
```

又或是：

```go
idx = strings.LastIndex(address, "@")
if idx != -1 {
  host = address[idx+1:]
} else {
  host = address
}
```

经常要反复写一些繁琐的代码，提案提出者表示不愉快。

## 新提案

### 实施内容

建议新增 Cut 方法到 strings 标准库：

```go
func Cut(s, sep string) (before, after string, found bool) {
	if i := Index(s, sep); i >= 0 {
		return s[:i], s[i+len(sep):], true
	}
	return s, "", false
}
```

同步也要在 bytes 标准库：  

```go
func Cut(s, sep []byte) (before, after []byte, found bool)
```

这样一来，就可以从原本的：

```go
	eq := strings.IndexByte(rec, '=')
	if eq == -1 {
		return "", "", s, ErrHeader
	}
	k, v = rec[:eq], rec[eq+1:]
```

变成：

```go
	k, v, ok = strings.Cut(rec, "=")
	if !ok {
		return "", "", s, ErrHeader
	}
```

写法上会更优雅，在复杂的场景下会更具可读性和抽象级别。

### 接受原因

可能就有小伙伴会吐槽了，Go 居然只为了节省 1 行代码，就搞了个新函数，这还是大道至简吗？

实际上，在官方团队（Russ Cox）介入后，他对 Go 主仓库进行了分析，搜索了相关类似函数的使用：
- strings.Index。
- strings.IndexByte。
- strings.IndexRune。

统计后，转换为了可以使用 `strings.Cut` 的用法，在例子和测试数据之外有 311 个索引调用。

排除了一些确实不需要的，剩下 285 个调用。在这些调用中，有 221 次是最好写成 Cut 方法的，能更优雅。

![](https://files.mdnice.com/user/3610/a1a61fd3-1ca0-448a-b503-551433635992.png)

也就是说，有现有的 Go 代码中，有 77% 可以用新增的 Cut 函数写得更清楚，可读性和抽象可以做得更好。

Go 主仓库确实存在如此重复的代码，他认为这也是非常不可思议的！

## 总结

Go1.18 的新特性中，Cut 虽然只是新增了一个方法，看上去无伤大雅。

但类似 Cut 方法的用法，在 Go 的主版本中其实已经被发明了两次。

该新方法的出现，可以同时取代并简化四个不同的标准库函数：Index、IndexByte、IndexRune 和 SplitN 中的绝大部分用法。
 
由于这些原因，最终将 Cut 添加到标准库中。

你觉得怎么样？：）

## 参考
- [bytes, strings: add Cut](https://github.com/golang/go/issues/46336)

================================================
FILE: content/posts/go/118-leader-generics.md
================================================
---
title: "回归现实：Go Leader 对 1.18 泛型的期望"
date: 2021-12-31T12:55:16+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间根据 Go 泛型的最新动态，我写了一篇《[出泛型后 API 怎么办？Go 开发者要注意了](https://mp.weixin.qq.com/s/yWEM2EAwv80ZUFjbKGtpNA)》文章，引发了不少小伙伴的热议。

Go 核心开发团队的现任 Leader 
@Russ Cox 在 golang-dev 中正式发表《[expectations for generics in Go 1.18](https://groups.google.com/g/golang-dev/c/iuB22_G9Kbo)》对 Go 泛型给出了 “期待”，可以认为是后续的计划了。


![](https://files.mdnice.com/user/3610/e4693268-eff4-4dd3-ab6b-e4c41d8728cc.png)


如果不出现严重的问题，Go 1.18 将会包括对泛型的支持，并且这次泛型的支持将会是有史以来最大的一次语言变化，对以下几点有顾虑：
- 最佳实践.
- 生产经验
- 兼容性承诺。

接下来，煎鱼带大家一起了解 Russ Cox 发表的 Go 泛型进程，知悉官方一手消息。

## 最佳实践

Go 团队表示不知道使用泛型的最佳实践是什么，所以给出的官方文档将无法就何时使用泛型和何时不使用泛型给出精确、明确的答案，只可以给出粗略的指导。

此处可以参考《Effective Go》的最初版本，是在不间断地写了一整年的 Go 代码后，才正式输出的。

![](https://files.mdnice.com/user/3610/034ab5db-f125-450d-bc97-9ea42ba94022.png)

按照现有的计划，官方只会提供关于如何使用泛型的文档，暂时无法提供任何关于风格、最佳实践的规定性文档。

在提供的标准库上，先是已经通过提案的 maps 和 slices库会先放到 golang.org/x/exp 中作为实验，不会保证向后兼容。待成熟后，再推广到标准库中。

![](https://files.mdnice.com/user/3610/b1d967a2-2ac7-4077-be2e-4d1c4d3565cb.png)

可以明确，Go 泛型出来后，社区就会陆续开始百花齐放，接着有官方输出推荐方法了，历史是如此的相似。

## 生产经验

目前 Go 团队没有关于泛型的生产经验，因此会在文档中给出明确提示，让大家在生产中使用泛型的时候应该适当谨慎。

泛型出来后，会陆续涉及到大量的重写工作，但是由于现在处于中间阶段。正在重写的 Go 1.18 工具链去同时适配泛型、非泛型代码是需要时间和经验的，有一定的风险。

因此泛型出来后，可能会出现一些意想不到的问题，仅在生产发现（教训）。

## 兼容性承诺

Go1.18 会和其他 Go1.x 版本一样，保证向后兼容的承诺：不会破坏用 Go 1.18 构建的代码，包括使用泛型的代码。

如果是最坏的情况，如果发现 Go 1.18 的语义有一些致命的问题，并需要改变它们（例如：在Go 1.19 中）。

将会使用 go.mod 文件的 go 行来确定该模块中的源文件是期待 Go 1.18 还是 Go 1.19+ 语义，以此实现版本控制。但目前来看，不需要这样做。

也建议急于使用 Go 泛型的开源库作者，做好泛型和非泛型版本代表的支持和隔离，这样对用户会更加的友好。

## 总结

可以明确的是，Go 泛型的整体推进方案，在这篇文章中均已说明。Go 官方团队也与许多第三方工具的作者进行沟通。

第三方工具可能不会在 Go 1.18 发布时就完全支持泛型，这会由各作者自行根据自己的时间表来更新。

煎鱼猜测推进节奏就是：
1. 支持泛型语法。
2. 观察。
3. 推进标准/工具库。
4. 逐步替换。
5. 修 BUG。
6. 观察、优化
7. 生产可用。

大概需要 2~3 个 Go 版本，需要 1~2 年，Go 泛型的各类配套组件就会基本完善，可用，转为持续优化了。

**你对 Go 官方的推进计划此怎么看呢**，欢迎在评论区留言和交流！

================================================
FILE: content/posts/go/118-module.md
================================================
---
title: "Go1.18 新特性：多 Module 工作区模式"
date: 2022-02-05T16:00:00+08:00
toc: true
images:
tags: 
  - go
  - go1.18
---

大家好，我是煎鱼。

Go 的依赖管理，也就是 Go Module。从推出到现在，也已经有了一定的年头了，吐槽一直很多，官方也不断地在进行完善。

Go1.18 将会推出一个新特性：Multi-Module Workspaces，用于支持 Module 多工作区，能解决以往的一系列问题。

今天将由煎鱼带大家一起深入学习。

## 背景

在日常使用 Go 工程时，总会遇到 2 个经典问题，特别的折腾人。

如下：
1. 依赖本地 replace module。
2. 依赖本地未发布的 module。

### replace module

第一个场景：像是平时在 Go 工程中，我们为了解决一些本地依赖，或是定制化代码。会在 go.mod 文件中使用 replace 做替换。

如下代码：

```go
replace golang.org/x/net => /Users/eddycjy/go/awesomeProject
```

这样就可以实现本地开发联调时的准确性。

问题就在这里：
- 本地路径：所设定的 replace 本质上转换的是本地的路径，也就是每个人都不一样。
- 仓库依赖：文件修改是会上传到 Git 仓库的，不小心传上去了，影响到其他开发同学，又或是每次上传都得重新改回去。

用户体验非常差，很折腾人。

### 未发布的 module

第二个场景：在做本地的 Go 项目开发时，可能会在本地同时开发多个库（项目库、工具库、第三方库）等。

如下代码：

```go
package main

import (
    "github.com/eddycjy/pkgutil"
)

func main() {
    pkgutil.PrintFish()
}
```

如果这个时候运行 `go run` 或是 `go mod tidy`，都不行，会运行失败。

报如下类似错误：

```
fatal: repository 'https://github.com/eddycjy/pkgutil/' not found
```

这个问题报错是因为 `github.com/eddycjy/pkgutil` 这个库，在 GitHub 是没有的，自然也就拉取不到。

解决方法：在 Go1.18 以前，我们会通过 replace（会遇到背景一的问题），又或是直接上传到 Github 上，自然也就能被 Go 工具链拉取到依赖了。

许多同学会发出灵魂质疑：Go 的依赖都必须要上传到 GitHub 吗，强绑定？

对新入门的同学非常不友好，很要命。

## 工作区模式

在社区的多轮反馈下，Michael Matloob 提出了提案《[Proposal: Multi-Module Workspaces in cmd/go](https://go.googlesource.com/proposal/+/master/design/45713-workspace.md "Proposal: Multi-Module Workspaces in cmd/go")》进行了大量的讨论和实施，在 Go1.18 正式落地。

新提案的一个核心概念，就是增加了 `go work` 工作区的概念，针对的是 Go Module 的依赖管理模式。

其能够在本地项目的 go.work 文件中，通过设置一系列依赖的模块本地路径，再将**路径下的模块组成一个当前的工作区**，他的读取优先级是最高的。

我们可以通过 `go help` 来查看，如下：

```
$ go1.18beta1 help work
Usage:

	go work <command> [arguments]

The commands are:

	edit        edit go.work from tools or scripts
	init        initialize workspace file
	sync        sync workspace build list to modules
	use         add modules to workspace file

Use "go help work <command>" for more information about a command.
```

只要执行 `go work init` 就可以初始化一个新的工作区，后面跟的参数就是要生成的具体子模块 mod。

命令如下：

```go
go work init ./mod ./tools
```

项目目录如下：

```
awesomeProject
├── mod
│   ├── go.mod      // 子模块
│   └── main.go
├── go.work         // 工作区
└── tools
    ├── fish.go
    └── go.mod      // 子模块
```

生成的 go.work 文件内容：

```
go 1.18

use (
    ./mod 
    ./tools
)
```

新的 go.work 与 go.mod 语法一致，也可以使用 replace 语法：

```
go 1.18

use (...)

replace golang.org/x/net => example.com/fork/net v1.4.5
```

go.work 文件内共支持三个指令：
- go：声明 go 版本号，主要用于后续新语义的版本控制。
- use：声明应用所依赖模块的具体文件路径，路径可以是绝对路径或相对路径，可以在应用命目录外均可。
- replace：声明替换某个模块依赖的导入路径，优先级高级 go.mod 中的 replace 指令。

若想要禁用工作区模式，可以通过 `-workfile=off` 指令来指定。

也就是在运行时执行如下命令：

```
go run -workfile=off main.go

go build -workfile=off
```

go.work 文件是不需要提交到 Git 仓库上的，否则就比较折腾了。

只要你在 Go 项目中设置了 go.work 文件，那么在运行和编译时就会进入到工作区模式，会优先以工作区的配置为最高优先级，来适配本地开发的诉求。

至此，工作区的核心知识就介绍完毕了。

## 总结

今天给大家介绍了 Go1.18 的新特性：多 Module 工作区模式。其本质上还是为了解决本地开发的诉求。

由于 go.mod 文件是与项目强关联的，基本都会上传到 Git 仓库中，很难在这上面动刀子。直接就造了个 go.work 出来，纯本地使用，方便快捷。

使用新的 go.work，就可以在完全是本地文件上各种捣鼓了，不会对其他成员开发有其他影响。

你觉得怎么样呢？：）


================================================
FILE: content/posts/go/4errors.md
================================================
---
title: "大家对 Go 错误处理的 4 个误解！"
date: 2021-12-31T12:55:04+08:00
draft: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

Go 语言中错误处理的机制一直是各大 Gopher 热议的问题。甚至一直有人寄望 Go 支持 `throw` 和 `catch` 关键字，实现与其他语言类似的特性。

今天煎鱼带大家了解几个 Go 语言的错误处理中，大家最关心的问题：
1. 为什么不支持 try-catch？
2. 为什么不支持全局捕获的机制？
3. 为什么要这么设计错误处理？
4. 未来的错误处理机制会怎么样？

## 落寞的 try-catch

在 Go1 时，大家知道基本不可能支持。于是打起了 Go2 的主意。为什么 Go 就不能支持 try-catch 组合拳？

上一年宣发了 Go2 的构想，所以在 2020 年就有小伙伴乘机提出过类似 《[proposal: Go 2: use keywords throw, catch, and guard to handle errors](https://github.com/golang/go/issues/40583 "proposal: Go 2: use keywords throw, catch, and guard to handle errors")》的提案。

下面来自该提案的演示，Go1 的错误处理： 

```golang
type data struct {}

func (d data) bar() (string, error) {
    return "", errors.New("err")
}

func foo() (data, error) {
    return data{}, errors.New("err")
}

func do () (string, error) {
    d, err := foo()
    if err != nil {
        return "", err
    }

    s, err := d.bar()
    if err != nil {
        return "", err
    }

    return s, nil
}
```

新提案所改造的方式：

```golang
type data struct {}

func (d data) bar() string {
    throw "", errors.New("err")
}

func foo() (d data) {
    throw errors.New("err")
    return
}

func do () (string, error) {
    catch err {
        return "", err 
    }

    s := foo().bar()
    return s, nil
}
```

不过答复非常明确，@davecheney 在底下回复“以最强烈的措辞，不（In the strongest possible terms, no）”。这可让人懵了圈，为什么这么硬呢？

其实 Go 官方早在《[Error Handling — Problem Overview](https://go.googlesource.com/proposal/+/master/design/go2draft-error-handling-overview.md "Error Handling — Problem Overview")》提案早已明确提过，Go 官方在**设计上会有意识地选择使用显式错误结果和显式错误检查**。

结合《[language: Go 2: error handling meta issue](https://github.com/golang/go/issues/40432 "language: Go 2: error handling meta issue")》可得知，要拒绝 try-catch 关键字的主要原因是：
- 会**涉及到额外的流程控制**，因为使用 try 的复杂表达式，会导致函数意外返回。
- 在表达式层面上没有流程控制结构，只有 panic 关键字，它不只是从一个函数返回。

说白了，就是设计理念不合，加之实现上也不大合理。在以往的多轮讨论中早已被 Go 团队拒绝了。

反之 Go 团队倒是一遍遍在回答这个问题，已经不大耐烦了，直接都整理了 issues 版的 FAQ 了。

## 想捕获所有 panic

在 Go 语言中，有一个点，很多新同学会不一样碰到的。那就是在 goroutine 中如果 panic 了，没有加 recover 关键字（有时候也会忘记），就会导致程序崩溃。

又或是以为加了 recover 就能保障一个 goroutine 下所派生出来的 goroutine 所产生的 panic，一劳永逸。

但现实总是会让人迷惑，我经常会看到有同学提出类似的疑惑：

![来自 Go 读者交流群](https://files.mdnice.com/user/3610/8e3127ef-7cbe-4952-8780-f8812f921f45.png)

这时候，有其他语言经验的同学中，又有想到了一个利器。能不能设置一个全局的错误处理 handler。

像是 PHP 语言也可以有类似的方法：

```
set_error_handler();
set_exception_handler();
register_shutdown_function();
```

显然，Go 语言中并没有类似的东西。归类一下，我们聚焦以下两个问题：
1. 为什么 recover 不能捕获更上层的 panic？
2. 为什么 Go 没有全局的错误处理方法？

### 源码层面

如果是讲设计的话，其实只是通过 Go 的 GMP 模型和 defer+panic+recver 的源码剖析就能知道了。

![](https://files.mdnice.com/user/3610/42998ba0-84cc-4fe5-b88d-b9400dd1698b.png)

本质上 defer+panic 都是挂载在 G 上的，可查看我以前写的《[深入理解 Go panic and recover](https://eddycjy.com/posts/go/panic/2019-05-21-panic-and-recover/ "深入理解 Go panic and recover")》，你会有更多深入的理解。

### 设计思想

在本文中我们不能仅限于源码，需要更深挖，Go 设计者他的思想是什么，为什么就是不支持？

在 Go issues 中《[proposal: spec: allow fatal panic handler](https://github.com/golang/go/issues/32333 "proposal: spec: allow fatal panic handler")》、《[No way to catch errors from goroutines automatically](https://github.com/golang/go/issues/20161 "No way to catch errors from goroutines automatically") 》分别的针对性探讨过上述问题。

Go 团队的大当家 @Russ Cox 给出了明确的答复：**Go 语言的设计立场是错误恢复应该在本地完成，或者完全在一个单独的进程中完成**。

![](https://files.mdnice.com/user/3610/cb6fac34-ba12-40fd-98d3-f177e00ee39f.png)

这就是为什么 Go 语言不能跨 goroutines 从 panic 中恢复，也不能从 throw 中恢复的根本原因，是**语言设计层面的思想所决定**。

在源码剖析时，你所看到的整套 GMP+defer+panic+recover 的机制机制，就是跟随着这个设计思想去编写和发展的。

设计思想决定源码实现。

### 建议方式

从 Go 语言层面去动摇这个设计思想，目前来看可能性很低。至少 2021 年的现在没有看到改观。

整体上会建议提供公共的 Go 方法去规避这种情况。参考 issues 所提供的范例如下：

```golang
recovery.SafeGo(logger, func() {
              method(all parameters)
	})

func SafeGo(logger logging.ILogger, f func()) {
	go func() {
		defer func() {
			if panicMessage := recover(); panicMessage != nil {
				...
			}
		}()

		f()
	}()
}
```

是不是感觉似曾相识？

每家公司的内部库都应该有这么一个工具方法，规避偶尔忘记的 goroutine recover 所引发的奇奇怪怪问题。

也可以参照建议，利用一个单独的进程（Go 语言中是 goroutine）去统一处理这些 panic，不过这比较麻烦，较少见。

## 未来会如何

Go 社区对 Go 语言未来的错误处理机制非常关心，因为 Go1 已经米已成炊，希望在 Go2 上解决错误处理机制的问题。

期望 Go2 核心要处理的包含如下几点（#40432）：

1. 对于 Go2，我们希望使错误检查更加轻便，减少专门用于错误检查的 Go 程序代码的数量。我们还想让写错误处理更方便，减少程序员花时间写错误处理的可能性。
2. 错误检查和错误处理都必须保持明确，即在程序文本中可见。我们不希望重复异常处理的陷阱。
3. 现有的代码必须继续工作，并保持与现在一样的有效性。任何改变都必须与现有的代码相互配合。

为此，许多人提过不少新的提案...很可惜，截止 2021.08 月底为止，有许多人试图改变语言层面以达到这些目标，但没有一个新的提案被接受。

现在也有许多变更并入 Go2 提案，主要是 error-handling 方面的优化。

大家有兴趣可以看看我之前写的：《[先睹为快，Go2 Error 的挣扎之路](https://mp.weixin.qq.com/s/XILveKzh07BOQnqxYDKQsA)》，相信能给你带来不少新知识。

## 总结

看到这里，我们不由得想到。为什么，为什么在 21 世纪前者已经有了这么多优秀的语言，Go 语言的错误处理机制依然这么的难抉择？

显然 Go 语言的开发团队是有自己的设计哲学和思想的，否则 “less is more” 也不会如此广泛流传。

这存在着一系列既要也要的问题。欢迎大家关注煎鱼，后续我们也可以面向 Go 后续的错误处理持续的关注和讨论！

================================================
FILE: content/posts/go/again-mutex.md
================================================
---
title: "Go 为什么不支持可重入锁？"
date: 2021-12-31T12:55:24+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

程序里的锁，是很多小伙伴在写分布式应用时用的最多的一个利器之一。

使用 Go 的同学里，绝大部分都有其他语言的经验，就会对其中一点有疑惑，那就是 **Go 里的锁，竟然不支持可重入**？

为此，今天煎鱼带大家一起来了解这里的设计考量，看看为什么。

## 可重入锁

如果对已经上锁的普通互斥锁进行 “加锁” 操作，其结果要么失败，要么会阻塞至解锁。

锁的场景如下：
- 在加锁上：如果是可重入互斥锁，当前尝试加锁的线程如果就是持有该锁的线程时，加锁操作就会成功。
- 在解锁上：可重入互斥锁一般都会记录被加锁的次数，只有执行相同次数的解锁操作才会真正解锁。

简单来讲，可重入互斥锁是互斥锁的一种，同一线程对其多次加锁不会产生死锁，又或是导致阻塞。

不同语言间实现可能或多或少有些区别，但大体意思差不多。

请你想一下，Go 是怎么样的呢？

## Go 支持情况

我们看到以下这个 Go 互斥锁例子：

```golang
var mu sync.Mutex

func main() {
	mu.Lock()
	mu.Lock()
}
```

这段 Go 程序会阻塞吗？不会，会报以下错误：

```
fatal error: all goroutines are asleep - deadlock!
```

Go 显然是不支持可重入互斥锁的。

## 官方回复

### Go 设计原则

在工程中使用互斥的根本原因是：为了保护不变量，也可以用于保护内、外部的不变量。

基于此，Go 在互斥锁设计上会遵守这几个原则。如下：
- 在调用 `mutex.Lock` 方法时，要保证这些变量的不变性保持，不会在后续的过程中被破坏。
- 在调用 `mu.Unlock` 方法时，要保证：
    - 程序不再需要依赖那些不变量。
    - 如果程序在互斥锁加锁期间破坏了它们，则需要确保已经恢复了它们。

### 不支持的原因

讲了 Go 自己的设计原则后，那为什么不支持可重入呢？

其实 Russ Cox 于 2010 年在《[Experimenting with GO](https://groups.google.com/g/golang-nuts/c/XqW1qcuZgKg/m/Ui3nQkeLV80J "Experimenting with GO")》就给出了答复，认为递归（又称：重入）互斥是个坏主意，这个设计并不好。

我们可以结合官方的例子来理解。

如下：

```golang
func F() {
        mu.Lock()
        ... do some stuff ...
        G()
        ... do some more stuff ...
        mu.Unlock()
}

func G() {
        mu.Lock()
        ... do some stuff ...
        mu.Unlock()
}
```

在上述代码中，我们在 `F` 方法中调用 `mu.Lock` 方法加上了锁。如果支持可重入锁，接着就会进入到 `G` 方法中。

此时就会有一个致命的问题，你**不知道 `F` 和 `G` 方法加锁后是不是做了什么事情**，从而导致破坏了不变量，毕竟随手起几个协程做点坏事，也是完全可能的。

这对于 Go 是无法接受的，可重入的设计**违反了前面所提到的设计理念**，也就是：“要保证这些变量的不变性保持，不会在后续的过程中被破坏”。

基于上述原因，Go 官方团队选择了没有支持该项特性。

## 总结

Go 互斥锁没有支持可重入锁的设计，也是喜欢的大道至简的思路了，可能的干扰比较多，不如直接简单的来。

你在工作过程中有没有类似的疑惑呢，欢迎大家在评论区留言和交流：）

================================================
FILE: content/posts/go/annotation.md
================================================
---
title: "Go：我有注解，Java：不，你没有！"
date: 2021-12-31T12:55:11+08:00
toc: true
images:
tags: 
  - go
  - 为什么
---

大家好，我是煎鱼。

作为一位 Go 程序员，你会发现身边的同事大多都拥有其他语言的编写经验。那势必就会遇到一点，要把新学到的知识和以前的知识建立连接。

![图来自网络](https://files.mdnice.com/user/3610/050a9802-1ca2-4634-859d-325a09d418c5.png)

特殊在于，Go 有些特性是其他语言有，他没有的。最经典的就是 N 位 Java 同学寻找 Go 语言的注解在哪里，总要解释。

为此，今天煎鱼就带大家了解一下 Go 语言的注解的使用和情况。

## 什么是注解

### 了解历史

注解（Annotation）最早出现自何处，翻了一圈并没有找到。但可以明确，在注解的使用中，Java 注解最为经典，为了便于理解，因此我们基于 Java 做初步的注解理解。

![](https://files.mdnice.com/user/3610/3c9e2434-c5f4-4d7a-bd2d-a8b582b570c8.png)

在 2002 年，JSR-175 提出了 《[A Metadata Facility for the Java Programming Language](https://jcp.org/en/jsr/detail?id=175)》，也就是为 Java 编程语言提供元数据工具。

这就是现在使用最广泛地注解（Annotation）的来源。
示例如下：

```golang
// @annotation1
// @annotation2
func Hello() string {
        return ""
}
```

在格式上均以 “@” 作为注解标识来使用。

### 注解例子

摘抄自 @wikipedia 的一个注解例子：

```java
  //等同于 @Edible(value = true)
  @Edible(true)
  Item item = new Carrot();

  public @interface Edible {
    boolean value() default false;
  }

  @Author(first = "Oompah", last = "Loompah")
  Book book = new Book();

  public @interface Author {
    String first();
    String last();
  }
  
  // 该标注可以在运行时通过反射访问。
  @Retention(RetentionPolicy.RUNTIME) 
  // 该标注只用于类内方法。
  @Target({ElementType.METHOD})
  public @interface Tweezable {
  }

```

在上述例子中，通过注解去做了一系列的定义、声明、赋值等。若是对语言既有注解不熟，或是做的比较复杂的注解，就会有一定的理解成本。

在业内也常常会说，**注解就是 “在源码上进行编码”**，注解的存在，有着明确的优缺点。你觉得呢？

## 注解的作用

在注解的的作用上，分为如下几点：
1. 为编译器提供信息：注释可以被编译器用来检测错误或支持警告。
2. 编译时和部署时处理：软件工具可以处理注释信息以生成代码、XML文件等。
3. 运行时处理：有些注解可以在运行时检查，并用于其他用途。

## Go 注解在哪里

### 现状 

Go 语言本身并没有原生支持强大的注解，仅限于以下两种：
- 编译时生成：go:generate
- 编译时约束：go:build

但这先按不足以作为一个函数注解来使用，也无法形成像 Python 那样的装饰器行为。

### 为什么不支持

Go issues 上有人提过类似的提案：

![](https://files.mdnice.com/user/3610/9695f163-65e8-456a-8dce-bb8551739016.png)

Go Contributor @ianlancetaylor 给出了明确的答复，Go在设计上更倾向于明确的、显式的编程风格。

思考的优缺点如下：
- 优势：不知道 Go 能从添加装饰器中得到什么好处，没能在 issues 上明确论证。
- 缺点：是明确的，会存在意外设置的情况。

因如下原因，没有接受注解：
- 对比现有代码方法，这种装饰器的新的方法没有提供比现有方法更多的优势，大到足矣推翻原有的设计思路。
- 社区内的投票，支持的也很少（基于表情符号的投票），用户反馈不多。

可能有小伙伴会说了，有注解做装饰器了，代码会简洁不少。

对此 Go 团队的态度很明确：

![](https://files.mdnice.com/user/3610/bb357e12-9b15-4729-9381-977d164b6b04.png)

Go 认为**可读性更重要**，如果只是额外多写一点代码，在权衡后，还是可以接受的。

## 用 Go 实现注解

虽然 Go 语言官方没有原生的完整支持，但开源社区中也有小伙伴已经放出了大招，借助各项周边工具和库来实现特定的函数注解功能。


GitHub 项目分别如下：
- [MarcGrol/golangAnnotations](github.com/MarcGrol/golangAnnotations)
- [u2takey/go-annotation](https://github.com/u2takey/go-annotation)

使用示例如下：

```golang
package tourdefrance

//go:generate golangAnnotations -input-dir .

// @RestService( path = "/api/tour" )
type TourService struct{}

type EtappeResult struct{ ... }

// @RestOperation( method = "PUT", path = "/{year}/etappe/{etappeUid}" )
func (ts *TourService) addEtappeResults(c context.Context, year int, etappeUid string, results EtappeResult) error {
	return nil
}
```

对 Go 注解的使用感兴趣的小伙伴可以自行查阅使用手册。

我们更多的关心，Go 原生都没支持，那么开源库都是如何实现的呢？在此我们借助 [MarcGrol/golangAnnotations](github.com/MarcGrol/golangAnnotations) 项目所提供的思路来讲解。

分为三个步骤：
1. 解析代码。
2. 模板处理。
3. 生成代码。

### 解析 AST

首先，我们需要用用 go/ast 标准库获取代码所生成的 AST Tree 中需要的内容和结构。

示例代码如下：

```shell
parsedSources := ParsedSources{
    PackageName: "tourdefrance",
    Structs:     []model.Struct{
        {
      	     DocLines:   []string{"// @RestService( path = "/api/tour" )"},
      	     Name:       "TourService",
      	     Operations: []model.Operation{
                {
              	    DocLines:   []string{"// @RestOperation( method = "PUT", path = "/{year}/etappe/{etappeUid}"},
              	    ...
                },
            },
        },
    },
}
```
我们可以看到，在 AST Tree 中能够获取到在示例代码中所定义的注解内容，我们就可以依据此去做很多奇奇怪怪的事情了。

### 模板生成

紧接着，在知道了注解的输入是什么后，我们只需要根据实际情况，编写对应的模板生成器 code-generator 就可以了。

我们会基于 text/template 标准库来实现，比较经典的像是 [kubernetes/code-generator](https://github.com/kubernetes/code-generator) 是一个可以参考的实现。

代码实现完毕后，将其编译成 go plugin，便于我们在下一步调用就可以了。

### 代码生成

最后，万事俱备只欠东风。差的就是告诉工具，哪些 Go 文件中包含注解，需要我们去生成的。

这时候我们可以使用 `//go:generate` 在 Go 文件声明。就像前面的项目中所说的：

```
//go:generate golangAnnotations -input-dir .
```

声明该 Go 文件需要生成，并调用前面编写好的 golangAnnotations 二进制文件，就可以实现基本的 Go 注解生成了。

## 总结

今天在这篇文章中，我们介绍了注解（Annotation）的历史背景。同时我们针对 Go 语言目前原生的注解支持情况进行了说明。

也面向为什么 Go 没有像 Java 那样支持强大的注解进行了基于 Go 官方团队的原因解释。如果希望在 Go 实现注解的，也提供了相应的开源技术方案。

**你觉得 Go 语言是否需要强大的注解支持**呢，欢迎你在评论区留言和讨论！

================================================
FILE: content/posts/go/any.md
================================================
---
title: "Go 新关键字 any，interface 会成历史吗？"
date: 2021-12-31T12:55:21+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

大家在看 Go1.18 泛型的代码时，不知道是否有留意到一个新的关键字 any。

例子如下：

```golang
func Print[T any](s []T) {}
```

之前没有专门提过，但有没有小伙伴以为这个关键字，是泛型代码专属的？

其实不是...在这次新的 Go1.18 更新中，any 是作为一个新的关键字出现，**any 有一个真身，本质上是 interface{} 的别名**：

```golang
type any = interface{}
```

也就是，在常规代码中，也可以直接使用：

```golang
func f(a any) {
	switch a.(type) {
	case int:
		fmt.Println("进脑子煎鱼了")
	case float64:
		fmt.Println("煎鱼进脑子了")
	case string:
		fmt.Println("脑子进煎鱼了")
	}
}

func main() {
	f(2)
	f(3.1415)
	f("煎鱼好！")
}
```

从使用层面来讲，新的关键字 any 会比 interface{} 方便不少，毕竟少打了好多个词，更快了，其实也是参照现有 rune 类型的做法。

增加新关键字后的对比如下：

| 长声明    |  短声明   |
| --- | --- |
|  func f[T interface{}](s []T) []T	   |  func f[T any](s []T) []T
  func f(a interface{})	 | func f(a any)
 |  var a interface{}	   |  var a any   |

我们在了解他的便利性后，再从代码一致性和可读性来讲，是有些问题的，会造成一定的疑惑。

因此前两天有人提出了《[all: rewrite interface{} to any](https://github.com/golang/go/issues/49884)》的需求，打算把内部所有的代码都重写一遍。

![](https://files.mdnice.com/user/3610/06687ddd-e224-4499-892b-3869ee1fc1d0.png)

你可能会以为是人肉手工改？那肯定不是，Go 官方发起了 CL 进行批量修改。

我们在日常的工程中，也可以和他们一样，直接借用 Go 工具链来实现替换。

如下：

```golang
gofmt -w -r 'interface{} -> any' ./...
```

听到这个消息时，我的朋友咸鱼就大惊了，在想 interface{} 会不会成为历史，被新的关键字 any 完全替代？

![](https://files.mdnice.com/user/3610/41a70c0c-284c-44c7-9b15-a1ee37545424.png)

显然，答案是不会的。因为 **Go1 有兼容性的保证**，肯定不会在现阶段删除。不过后续会出现一个现象，就是我们的 Go 工程中，有人用 any，有人用 interface{}，会在代码可读性上比较伤人。

不过我们也可以学 Go 官方，在 linter 流程中借助 gofmt 工具来强行把所有 interface{} 都替换成 any 来实现代码的一致性。 

这次变更，感觉是个**美学**的问题，你对此怎么看呢？有没有也希望哪些东西有别名，**欢迎大家在评论区留言和交流**：）

================================================
FILE: content/posts/go/class-extends.md
================================================
---
title: "Go 为什么不支持类和继承？"
date: 2021-12-31T12:55:22+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

大家在早期学习 Go 时，一旦跨过语法的阶段后。马上就会进入到一个新的纠结点，Go 不支持面向对象吗？

![](https://files.mdnice.com/user/3610/a299d98d-e46c-4a6d-8362-02f957e86b10.png)


这门编程语言里没有类（class）、继承（extends），~~没法一把搜了，面试问啥面向对象（OOP）~~？

今天煎鱼就带大家一起来了解这之中的思考，Go 真的不支持吗？

## 类和继承

### 类是什么

类（class）在面向对象编程中是一种面向对象计算机编程语言的构造，是创建对象的蓝图，描述了所创建的对象共同的特性和方法（via @维基百科）。

例子如下：

```php
class SimpleClass
{
    // 声明属性
    public $var = '脑子进煎鱼了';

    // 声明方法
    public function displayVar() {
        echo $this->var;
    }
}
```

每个类的定义都以关键字 class 开头，后面跟着类名，后面跟着一对花括号，里面包含有类的属性与方法的定义。

### 继承是什么

继承是面向对象软件技术当中的一个概念，如果一个类别 B “继承自”另一个类别 A，就把这个 B 称为 “A的子类”，而把 A 称为 “B的父类别” 也可以称 “A 是 B 的超类”（via @维基百科）。

例子如下：

```php
// 父类
class Foo
{
    public function printItem($string)
    {
        echo '煎鱼1: ' . $string . PHP_EOL;
    }
    
    public function printPHP()
    {
        echo 'PHP is great.' . PHP_EOL;
    }
}

// 子类
class Bar extends Foo
{
    public function printItem($string)
    {
        echo '煎鱼2: ' . $string . PHP_EOL;
    }
}
```

继承有如下两个特性：
- 子类具有父类别的各种属性和方法，不需要再次编写相同的代码。
- 子类别继承父类时，可以重新定义某些属性，并重写某些方法，使其获得与父类别不同的功能。

## 结构和组合

在 Go 里就比较 ”特别“ 了，因为没有传统的类，也没有继承。

取而代之的是结构和组合的方式。这也是业内对 Go 是否 OOP 争议最大的地方。

### 结构体

我们可以在 Go 中通过结构体的方式来组织代码，达到类似类的方式。

例子如下：

```golang
package main

import "fmt"

type person struct {
    name string
    age  int
}

func(p *person) hello(){}

func newPerson(name string) *person {
    p := person{name: name}
    p.age = 42
    return &p
}

func main() {
    fmt.Println(person{"煎鱼1", 22})
    fmt.Println(person{name: "煎鱼2", age: 33})
    ...
}
```

在上述代码中，我们可以定义结构体内的属性，也可以针对结构体这些类型定义只属于他们的方法。

在声明实例上，可以配合 `newXXX` 的初始化方法来生成，这是 Go 里约定俗成的方式。

### 组合

类的声明采取结构体的方式取代后，也可以配套使用 ”组合“ 来达到类似继承的效果。

例子如下：

```golang
type man struct {
	name string
}

func (m *man) hello1() {}

type person struct {
	man
	name string
}

func (p *person) hello2() {}

func newPerson(name string) *person {
	p := person{name: name}
	return &p
}

func main() {
	p := newPerson("脑子进煎鱼了")
	p.hello1()
}
```

在上述代码中，我们分别定义了 man 和 person 两个结构体，并将 man 嵌入到 person 中，形成组合。

你可以在 main 方法中能够看到，person 实例是可以使用和调用 man 实例的一些公开属性和方法的。

在简单的使用效果上会与继承有些接近。

## Go 是面向对象的语言吗

“Go 语言是否一门面向对象的语言？”，这是一个日经话题。官方 FAQ 给出的答复是：

![](https://files.mdnice.com/user/3610/159601a9-b428-4958-9f85-2214aea30127.png)

是的，也不是。原因是：

- Go 有类型和方法，并且允许面向对象的编程风格，但没有类型层次。
- Go 中的 "接口 "概念提供了一种不同的方法，我们认为这种方法易于使用，而且在某些方面更加通用。还有一些方法可以将类型嵌入到其他类型中，以提供类似的东西，但不等同于子类。
- Go 中的方法比 C++ 或 Java 中的方法更通用：它们可以为任何类型的数据定义，甚至是内置类型，如普通的、"未装箱的 "整数。它们并不局限于结构（类）。
- Go 由于缺乏类型层次，Go 中的 "对象 "比 C++ 或 Java 等语言更轻巧。

## 为什么不支持类和继承

有的人认为类和继承是面向对象的必要特性，必须要有，才能是面向对象的语言，但其实也并非如此。

面向对象（OOP）有不同的含义和解读，许多概念也可以通过结构体、组合和接口等方式进行表达，说是不支持传统的 OOP。

其实真相是 Go 是选择了另外一条路，也就是 ”**组合优于继承**“。我们所提到的类和继承并不是定义 OOP 的一种准则，只是协助完成 OOP 的方法之一。

不要本末倒置了，不让工具来定义 OOP 的理念。

## 总结

在今天这篇文章中，我们介绍了常说的类和继承的业内定义和使用案例。同时面向 Go 读者群里的疑惑，进行了解答。

实质上，Go 是 OOP，也不是 OOP。类和继承只是实现 OOP 的一种方式，但并不是没有这两者，他就不是 OOP 了。

不支持的原因也很明确，Go 在设计上，选择了组合优于继承的编程设计模式，它不是传统那种面向类型的范式。

你觉得呢，欢迎大家在评论区留言和交流：）
 
## 参考

- 为什么人们声称 Go 不是面向对象的，我是不是误读了什么？：https://www.reddit.com/r/golang/comments/a9rn6n/why_people_claim_that_go_is_not_object_oriented/
- 组合大于继承：https://en.wikipedia.org/wiki/Composition_over_inheritance
- Go 是面向对象的吗？：https://flaviocopes.com/golang-is-go-object-oriented/
- 类 vs 新型 + 接收器？：https://www.reddit.com/r/golang/comments/a8zgvm/class_vs_new_type_receiver/
- 结构而不是类：https://golangbot.com/structs-instead-of-classes/

================================================
FILE: content/posts/go/crawler/2018-03-21-douban-top250.md
================================================
---

title:      "爬取豆瓣电影 Top250"
date:       2018-03-21 12:30:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 数据分析
---

爬虫是标配了，看数据那一刻很有趣。第一个就从最最最简单最基础的爬虫开始写起吧！

项目地址：https://github.com/go-crawler/douban-movie

## 目标

我们的目标站点是 [豆瓣电影 Top250](https://movie.douban.com/top250)，估计大家都很眼熟了

本次爬取 8 个字段，用于简单的概括分析。具体的字段如下：

![image](https://i.loli.net/2018/03/20/5ab11596b8810.png)

简单的分析一下目标源

- 一页共 25 条
- 含分页（共 10 页）且分页规则是正常的
- 每一项的数据字段排序都是规则且不变

## 开始

由于量不大，我们的爬取步骤如下

- 分析页面，获取所有的分页
- 分析页面，循环爬取所有页面的电影信息
- 爬取的电影信息入库

### 安装

```
$ go get -u github.com/PuerkitoBio/goquery
```

### 运行

```
$ go run main.go
```

### 代码片段

#### 1、获取所有分页

```go
func ParsePages(doc *goquery.Document) (pages []Page) {
	pages = append(pages, Page{Page: 1, Url: ""})
	doc.Find("#content > div > div.article > div.paginator > a").Each(func(i int, s *goquery.Selection) {
		page, _ := strconv.Atoi(s.Text())
		url, _ := s.Attr("href")

		pages = append(pages, Page{
			Page: page,
			Url:  url,
		})
	})

	return pages
}
```

#### 2、分析豆瓣电影信息

```go
func ParseMovies(doc *goquery.Document) (movies []Movie) {
	doc.Find("#content > div > div.article > ol > li").Each(func(i int, s *goquery.Selection) {
		title := s.Find(".hd a span").Eq(0).Text()

		...

		movieDesc := strings.Split(DescInfo[1], "/")
		year := strings.TrimSpace(movieDesc[0])
		area := strings.TrimSpace(movieDesc[1])
		tag := strings.TrimSpace(movieDesc[2])

		star := s.Find(".bd .star .rating_num").Text()

		comment := strings.TrimSpace(s.Find(".bd .star span").Eq(3).Text())
		compile := regexp.MustCompile("[0-9]")
		comment = strings.Join(compile.FindAllString(comment, -1), "")

		quote := s.Find(".quote .inq").Text()

		...

		log.Printf("i: %d, movie: %v", i, movie)

		movies = append(movies, movie)
	})

	return movies
}
```

### 数据

![image](https://i.loli.net/2018/03/21/5ab1309594741.png)

![image](https://i.loli.net/2018/03/21/5ab131ca582f8.png)

![image](https://i.loli.net/2018/03/21/5ab130d3a00d9.png)

看到这些数据，你有什么想法呢，真是好奇 :=)


================================================
FILE: content/posts/go/crawler/2018-04-01-cars.md
================================================
---

title:      "爬取汽车之家 二手车产品库"
date:       2018-04-01 12:30:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 数据分析
---

项目地址：https://github.com/go-crawler/car-prices

## 目标

最近经常有人在耳边提起汽车之家，也好奇二手车在国内的价格是怎么样的，因此本次的目标站点是 [汽车之家](https://car.autohome.com.cn/2sc/440399/index.html) 的二手车产品库

![image](https://i.loli.net/2018/03/30/5abe47f82a01f.png)

分析目标源：

- 一页共 24 条
- 含分页，但这个老产品库，在 100 页后会存在问题，因此我们爬取 99 页
- 可以获取全部城市
- 共可爬取 19w+ 数据

## 开始

爬取步骤

- 获取全部的城市
- 拼装全部城市 URL 入队列
- 解析二手车页面结构
- 下一页 URL 入队列
- 循环拉取所有分页的二手车数据
- 循环拉取队列中城市的二手车数据
- 等待，确定队列中无新的 URL
- 爬取的二手车数据入库

### 获取城市

![image](https://i.loli.net/2018/03/31/5abeff11ef583.png)

通过页面查看，可发现在城市筛选区可得到全部的二手车城市列表，但是你仔细查阅代码。会发现它是 JS 加载进来的，城市也统一放在了一个变量中

![image](https://i.loli.net/2018/03/31/5abf056389cf0.png)

有两种提取方法

- 分析 JS 变量，提取出来
- 直接将 `areaJson` 复制出来作为变量解析

在这里我们直接将其复制粘贴出来即可，因为这是比较少变动的值

### 获取分页

![image](https://i.loli.net/2018/03/31/5abf08ec812e2.png)

通过分析页面可以得知分页链接是有一定规律的，例如：`/2sc/hangzhou/a0_0msdgscncgpi1ltocsp2exb4/`，可以发现 `sp%d`，`sp` 后面为页码

按照常理，可以通过预测所有分页链接，推入队列后 `go routine` 一波 即可快速拉取

但是在这老产品库存在一个问题，在超过 100 页后，下一页永远是 101 页

![image](https://i.loli.net/2018/03/31/5abf0e1e623ec.png)

因此我们采取比较传统的做法，通过拉取下一页的链接去访问，以便适应可能的分页链接改变； 100 页以后的分页展示也很奇怪，先忽视

### 获取二手车数据

页面结构较为固定，常规的清洗 HTML 即可

```go
func GetCars(doc *goquery.Document) (cars []QcCar) {
	cityName := GetCityName(doc)
	doc.Find(".piclist ul li:not(.line)").Each(func(i int, selection *goquery.Selection) {
		title := selection.Find(".title a").Text()
		price := selection.Find(".detail .detail-r").Find(".colf8").Text()
		kilometer := selection.Find(".detail .detail-l").Find("p").Eq(0).Text()
		year := selection.Find(".detail .detail-l").Find("p").Eq(1).Text()

		kilometer = strings.Join(compileNumber.FindAllString(kilometer, -1), "")
		year = strings.Join(compileNumber.FindAllString(strings.TrimSpace(year), -1), "")
		priceS, _ := strconv.ParseFloat(price, 64)
		kilometerS, _ := strconv.ParseFloat(kilometer, 64)
		yearS, _ := strconv.Atoi(year)

		cars = append(cars, QcCar{
			CityName: cityName,
			Title: title,
			Price: priceS,
			Kilometer: kilometerS,
			Year: yearS,
		})
	})

	return cars
}
```

## 数据

![image](https://i.loli.net/2018/03/31/5abf1d8042196.png)

![image](https://i.loli.net/2018/04/01/5abfbaa14b09c.png)

在各城市的平均价格对比中，我们可以发现北上广深里的北京、上海、深圳都在榜单上，而近年势头较猛的杭州直接占领了榜首，且后几名都有一些距离

而其他城市大致都是梯级下降的趋势，看来一线城市的二手车也是不便宜了，当然这只是均价

![image](https://i.loli.net/2018/03/31/5abf1dbc665f2.png)

我们可以看到价格和公里数的对比，上海、成都、郑州的等比差异是有点大，感觉有需求的话可以在价格和公里数上做一个衡量

![image](https://i.loli.net/2018/03/31/5abf1e1434edc.png)

这图有点儿有趣，粗略的统计了一下总公里数。在前几张图里，平均价格排名较高的统统没有出现在这里，反倒是呼和浩特、大庆、中山等出现在了榜首

是否侧面反应了一线城市的车辆更新换代较快，而较后的城市的车辆倒是换代较慢，公里数基本都杠杠的

![image](https://i.loli.net/2018/03/31/5abf1e4936640.png)

通过对标题的分析，可以得知车辆产品库的命名基本都是品牌名称+自动/手动+XXXX 款+属性，看标题就能知道个概况了

## 参考

### 爬虫项目地址

- https://github.com/go-crawler/car-prices




================================================
FILE: content/posts/go/crawler/2018-04-28-go2018.md
================================================
---

title:      "了解一下Golang的市场行情"
date:       2018-04-28 12:30:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 数据分析
---

项目地址：https://github.com/go-crawler/lagou_jobs

如果对你有所帮助，欢迎 Star，给文章来波赞，这样可以让更多的人看见  :)

## 目标

在工作中 Golang 已是一份子，想让大家了解一下 Golang 的市场行情，也想让更多的人熟悉它。因此主要是展示数据分析的结果

目标站点是 [某招聘网站](https://www.lagou.com/) 的职位数据抓取和分析，爬取城市分别为 北京、上海、广州、深圳、杭州、成都，再得出一个结论

### 分析

首先需要进行页面分析，找到我们的抓取方向

![image](https://i.loli.net/2018/04/26/5ae1e28a3412a.jpeg)

搜索 golang 关键字，打开页面 F12 就能看到它发送了四个请求，留意 positionAjax.json 这个请求

![image](https://i.loli.net/2018/04/26/5ae1efe538791.jpeg)

我们仔细研判这个接口的入参和出参

### 入参

1、Query String Param

- city：请求的城市

- needAddtionalResult：是否需要补充额外的参数，这里默认 false

2、Form Data

- first：是否首页
- pn：页码
- kd：关键字

### 出参

![image](https://i.loli.net/2018/04/26/5ae1f4c9920a9.jpeg)

就是它了，从返回结果可得出许多有用的信息

- companyFullName：公司全称
- companyLabelList：公司标签
- companyShortName：公司简称
- companySize：公司规模
- education：学历要求
- financeStage：融资阶段

等等~

### 分页

在上面两张图中，可以发现在 content 节点中包含 pageNo、pageSize 字段，content.positionResult 节点有 totalCount 字段，可以得知当前是第几页，每页显示多少条，当前的职位总条数

需要注意一下，分页的计算是要向上取整的

## 模拟浏览器头

User-Agent 可以用 [fake-useragent](https://github.com/EDDYCJY/fake-useragent) 这个项目来随机生成 UA 头 😄

## 数据

### 一、分布图

不同工作、工种，自然也会遍布在不同的工作区域，我们先了解一下各个城市的 Golang 工程师都主要在哪个区上班，心里留个底

#### 北京

![image](https://i.loli.net/2018/04/27/5ae291859667c.jpeg)

#### 上海

![image](https://i.loli.net/2018/04/27/5ae290856b774.jpeg)

#### 广州

![image](https://i.loli.net/2018/04/27/5ae28f1ab3e0c.jpeg)

#### 深圳

![image](https://i.loli.net/2018/04/27/5ae1fbebb1784.jpeg)

#### 杭州

![image](https://i.loli.net/2018/04/27/5ae29218c91dc.jpeg)

#### 成都

![image](https://i.loli.net/2018/04/27/5ae295b1059ed.jpeg)

### 二、招聘与职位数量对比

![image](https://i.loli.net/2018/04/27/5ae296b750dd8.png)

通过分析图中的数据，我们可以得知各城市的招聘职位数量

- 北京：348
- 上海：145
- 广州：37
- 成都：49
- 杭州：45
- 深圳：108

总共招聘的职位数量为 732 个，数量顺序分别为 北京 > 上海 > 深圳 > 成都 > 杭州 > 广州

还有另外一个关注点，就是招聘公司数量与职位的数量对比，可以看到 北京 招聘的职位数量为 348 个，而招聘的公司数量为 191 个，约为 1.82 的比例，也就是一家公司能提供两个 Golang 职位，它可能类别不同、（中级、中高级、高级）级别不同，具有一定可能性。而在广州，为 31 对比 37，虽然差额不大，但仍然存在这种现象

可以得出结果，Golang 在市场上具有一定的伸缩空间，也就是具有上升空间，一家公司会将 Golang 应用在多个不同的应用场景，也就是方向不同，需要的级别人才也就不同了

但是需要注意的是，Golang 的市场招聘人数目前份额还是较低，六个城市总数仅为 732 个，与其他大热语言相差有一定距离，需要谨慎

同时，面试 Golang 的人与其他大热语言相比会少些，职位的争夺是否小点呢？

### 三、招聘公司规模

![image](https://i.loli.net/2018/04/27/5ae2ab2babbd9.png)

通过查看招聘 Golang 工程师的公司规模，可以很直观的发现，微型公司使用 Golang 较少，其他类别的规模都有一定程度的应用，且差距不大。在 2000 人以上、50 - 150 人的公司规模中最受青睐

为什么呢，我认为有以下可能

- 大型公司结合场景，想通过 Golang 的特性来解决一些痛点问题
- 在小型公司 Golang 这颗新星实施起来更便捷，有一定的应用场景

你觉得呢，是不是应该有更多的选择它的原因？

### 四、学历要求

![image](https://s2.ax1x.com/2020/02/27/3dbTdP.png)

在招聘市场上，Golang 的招聘者更希望你是本科学历，大专和不限也有一定的份额，但市场份额相差较大

硕士学历要求的为两个，可以得出，在市场上 Golang 招聘者们对高学历的需求并不高，或者并不强制高学历

### 五、行业领域

![image](https://s2.ax1x.com/2020/02/27/3dqPiT.png)

在这里，重点关注 Golang 工程师的招聘公司都分别在什么行业领域，大头移动互联网是不容置疑的了，还可以惊喜的发现

- 数据服务
- 电子商务
- 金融
- 企业服务
- 游戏

Golang 在这几个方面都有所应用，说明了在市场上，Golang 的路子是比较广阔的，前景不错

同时，如果可以涉及多个领域的内容，想必身为工程师的你，肯定很激动

### 六、职位诱惑

![image](https://s2.ax1x.com/2020/02/27/3dqEQJ.png)

职位诱惑是投简历时必看的一点了，可以看到高频词条基本都是 IT 从业者关心的话题了，这里你懂的...

重点，我看到了一个 “免费三餐” 的词条命中 7 次，分别来自北京的海淀区、东城区、朝阳区，上海的黄浦区的七家不同的公司，辛苦了

### 七、行业、职位标签

![image](https://s2.ax1x.com/2020/02/27/3dqlWD.png)

在招聘 JD 中，描述和标签常用于给求职者了解这一职业的具体工作内容和其关联性

在图中你可以看到 Golang 常常和什么内容搭上边，这点很有意义哦

1、语言

- Java
- Python
- C/C++
- PHP

在图中可以看出，Golang 与以上四种语言有一定关联性，而 Java 和 Python 分别第一、第二名，可以说明市场上对复合型人才的渴望度更高，也许你不懂也行，但你懂了就最好（加分项）。需要你自身有多语言的经验，也便于和其他人对接

同时 Golang 目前存在许多内部转语言写的情况，所以这一点可以参考

2、职称

- 高级
- 资深
- 中级

特意将职称放在第二位，可以发现在市场上 Golang 标签的需求是 高级 > 资深 > 中级，关联第一项 “语言关联” 不难得出这个结论，因为语言只是解决问题的工具，到了中级及以上的工程师都是懂多门语言的居多，再采取不同的方案去解决应用场景上的问题

可得出结论，市场目前对 Golang 更期望是中高、高级、资深的人才，而中级的反而少一点点

大家可以努力再往上冲击冲击

3、组件

- Linux
- Redis
- Mysql

4、行业

- 云计算
- 信息安全
- 大数据
- 金融
- 软件开发

#### 八、薪资与工作年限

![image](https://s2.ax1x.com/2020/02/27/3dq3Se.jpg)

1、1-3 年

一个（成长）特殊的阶段，有个位数也有双位数的，大头可以到 15-30k，20-40k，而初级的也有 8-16k

2、3-5 年

厚积待发的阶段，薪酬范畴的跨度是较大，10-60k 的薪酬都有，这充分说明能力决定你的上下

3、5-10 年

核心，招聘网站上的招聘数量反而少，都会走内推或猎头，不需要特别介绍了

##### 小结

这一部分，相信是很多人关注的地方

在有的文章中会看到，他们的薪资部分是以平均值来展示的。我就很纳闷，因为对平均值并不是很关心，**重点是无法体现薪资幅度**。因此这里我会尽可能的把数据展现给你们看

（正文）从图表来看，Golang 当前的薪酬水平还是很不错的，市场能根据不同阶段（水平）的人给出一个好的价位

（题外话）看完之后希望你能知道以下内容

- 你当前工作年限的最高、最低薪资范畴
- 你的下一阶段的薪资范畴
- 为什么有的人高，有的人低
- 在大头部队还是小头，为什么
- 不要满足于平均值

### 九、融资阶段

![image](https://s2.ax1x.com/2020/02/27/3dqteI.png)

选用 Golang 的公司大多数都较为稳定，有一部分比较刺激 :)

#### 融资阶段与薪资范畴对比

##### 不需要融资

![image](https://s2.ax1x.com/2020/02/27/3dqyOs.png)

##### 上市公司

![image](https://s2.ax1x.com/2020/02/27/3dqWkV.png)

##### A 轮

![image](https://s2.ax1x.com/2020/02/27/3dqfYT.png)

##### B 轮

![image](https://s2.ax1x.com/2020/02/27/3dqTX9.png)

##### C 轮

![image](https://s2.ax1x.com/2020/02/27/3dqOk6.png)

##### D 轮以上

![image](https://s2.ax1x.com/2020/02/27/3dqz1e.png)

### 十、附近的地铁

Golang 工程师都驻扎在什么地铁站附近呢

经常在地铁上看到同行在看代码，来了解一下都分布在哪 :)

#### 北京

![image](https://s2.ax1x.com/2020/02/27/3dLCnA.png)

#### 上海

![image](https://s2.ax1x.com/2020/02/27/3dLkAP.png)

#### 广州

![image](https://s2.ax1x.com/2020/02/27/3dLAtf.png)

#### 深圳

![image](https://s2.ax1x.com/2020/02/27/3dLZ9S.png)

#### 杭州

![image](https://s2.ax1x.com/2020/02/27/3dLKns.png)

#### 成都

![image](https://s2.ax1x.com/2020/02/27/3dL3NV.png)

## 结论

如同官方所说 "Go has been on an amazing journey over the last 8+ years"，作为一门新生语言，一直在不断地发展，**缺点肯定是有的，你要去识别它**

### 从数量来看

单从这个招聘网站上来看，数量方面，与大热语言的招聘职位数量仍然有一定的差距，但 Golang 存在许多内部转语言开发的情况，当前展现出来的数据，**招聘数量不多，但质量不错**

### 从分布图来看

一线城市基本都有 Golang 的职位，虽然其他城市较少，但对于新语言来说是需要持续关注的过程，不能一刀切

### 从职称级别来看

Golang 中高、高级、资深仍然是占大头，给的薪资也基本符合市场行情

### 从方向来看

Golang 涉及的行业领域广泛，移动互联网、数据服务、电子商务、金融、企业服务、云计算等都是它的战场之一

### 从开源项目来看

docker、k8s、etcd、consul 都挺稳

---

总的来说，Golang 处于一个发展的阶段，市场行情也还行、应用场景较广，不过招聘数量不多，你又怎么看呢？

最后放上今天新发布的 Logo :)

![image](https://s2.ax1x.com/2020/02/27/3dLY3F.jpg)

如果对你有所帮助，欢迎 Star，给文章点个赞，这样可以让更多的人看见这篇文章

## 参考

- 项目地址：https://github.com/go-crawler/lagou_jobs


================================================
FILE: content/posts/go/defer/2019-05-27-defer.md
================================================
---

title:      "深入理解 Go defer"
date:       2019-05-27 12:30:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

在上一章节 《深入理解 Go panic and recover》中，我们发现了 `defer` 与其关联性极大，还是觉得非常有必要深入一下。希望通过本章节大家可以对 `defer` 关键字有一个深刻的理解，那么我们开始吧。你先等等，请排好队，我们这儿采取后进先出 LIFO 的出站方式...

## 特性

我们简单的过一下 `defer` 关键字的基础使用，让大家先有一个基础的认知

### 一、延迟调用

```go
func main() {
	defer log.Println("EDDYCJY.")

	log.Println("end.")
}
```

输出结果：

```
$ go run main.go
2019/05/19 21:15:02 end.
2019/05/19 21:15:02 EDDYCJY.
```

### 二、后进先出

```go
func main() {
	for i := 0; i < 6; i++ {
		defer log.Println("EDDYCJY" + strconv.Itoa(i) + ".")
	}


	log.Println("end.")
}
```

输出结果：

```
$ go run main.go
2019/05/19 21:19:17 end.
2019/05/19 21:19:17 EDDYCJY5.
2019/05/19 21:19:17 EDDYCJY4.
2019/05/19 21:19:17 EDDYCJY3.
2019/05/19 21:19:17 EDDYCJY2.
2019/05/19 21:19:17 EDDYCJY1.
2019/05/19 21:19:17 EDDYCJY0.
```

### 三、运行时间点

```go
func main() {
	func() {
		 defer log.Println("defer.EDDYCJY.")
	}()

	log.Println("main.EDDYCJY.")
}
```

输出结果：

```
$ go run main.go
2019/05/22 23:30:27 defer.EDDYCJY.
2019/05/22 23:30:27 main.EDDYCJY.
```

### 四、异常处理

```go
func main() {
	defer func() {
		if e := recover(); e != nil {
			log.Println("EDDYCJY.")
		}
	}()

	panic("end.")
}
```

输出结果：

```
$ go run main.go
2019/05/20 22:22:57 EDDYCJY.
```

## 源码剖析

```
$ go tool compile -S main.go
"".main STEXT size=163 args=0x0 locals=0x40
	...
	0x0059 00089 (main.go:6)	MOVQ	AX, 16(SP)
	0x005e 00094 (main.go:6)	MOVQ	$1, 24(SP)
	0x0067 00103 (main.go:6)	MOVQ	$1, 32(SP)
	0x0070 00112 (main.go:6)	CALL	runtime.deferproc(SB)
	0x0075 00117 (main.go:6)	TESTL	AX, AX
	0x0077 00119 (main.go:6)	JNE	137
	0x0079 00121 (main.go:7)	XCHGL	AX, AX
	0x007a 00122 (main.go:7)	CALL	runtime.deferreturn(SB)
	0x007f 00127 (main.go:7)	MOVQ	56(SP), BP
	0x0084 00132 (main.go:7)	ADDQ	$64, SP
	0x0088 00136 (main.go:7)	RET
	0x0089 00137 (main.go:6)	XCHGL	AX, AX
	0x008a 00138 (main.go:6)	CALL	runtime.deferreturn(SB)
	0x008f 00143 (main.go:6)	MOVQ	56(SP), BP
	0x0094 00148 (main.go:6)	ADDQ	$64, SP
	0x0098 00152 (main.go:6)	RET
	...
```

首先我们需要找到它，找到它实际对应什么执行代码。通过汇编代码，可得知涉及如下方法：

- runtime.deferproc
- runtime.deferreturn

很显然是运行时的方法，是对的人。我们继续往下走看看都分别承担了什么行为

### 数据结构

在开始前我们需要先介绍一下 `defer` 的基础单元 `_defer` 结构体，如下：

```go
type _defer struct {
	siz     int32
	started bool
	sp      uintptr // sp at time of defer
	pc      uintptr
	fn      *funcval
	_panic  *_panic // panic that is running defer
	link    *_defer
}

...
type funcval struct {
	fn uintptr
	// variable-size, fn-specific data here
}
```

- siz：所有传入参数的总大小
- started：该 `defer` 是否已经执行过
- sp：函数栈指针寄存器，一般指向当前函数栈的栈顶
- pc：程序计数器，有时称为指令指针(IP)，线程利用它来跟踪下一个要执行的指令。在大多数处理器中，PC 指向的是下一条指令，而不是当前指令
- fn：指向传入的函数地址和参数
- \_panic：指向 `_panic` 链表
- link：指向 `_defer` 链表

![image](https://s2.ax1x.com/2020/02/27/3dLNjJ.png)

### deferproc

```go
func deferproc(siz int32, fn *funcval) {
    ...
	sp := getcallersp()
	argp := uintptr(unsafe.Pointer(&fn)) + unsafe.Sizeof(fn)
	callerpc := getcallerpc()

	d := newdefer(siz)
    ...
	d.fn = fn
	d.pc = callerpc
	d.sp = sp
	switch siz {
	case 0:
		// Do nothing.
	case sys.PtrSize:
		*(*uintptr)(deferArgs(d)) = *(*uintptr)(unsafe.Pointer(argp))
	default:
		memmove(deferArgs(d), unsafe.Pointer(argp), uintptr(siz))
	}

	return0()
}
```

- 获取调用 `defer` 函数的函数栈指针、传入函数的参数具体地址以及 PC （程序计数器），也就是下一个要执行的指令。这些相当于是预备参数，便于后续的流转控制
- 创建一个新的 `defer` 最小单元 `_defer`，填入先前准备的参数
- 调用 `memmove` 将传入的参数存储到新 `_defer` （当前使用）中去，便于后续的使用
- 最后调用 `return0` 进行返回，这个函数非常重要。能够避免在 `deferproc` 中又因为返回 `return`，而诱发 `deferreturn` 方法的调用。其根本原因是一个停止 `panic` 的延迟方法会使 `deferproc` 返回 1，但在机制中如果 `deferproc` 返回不等于 0，将会总是检查返回值并跳转到函数的末尾。而 `return0` 返回的就是 0，因此可以防止重复调用

#### 小结

在**这个函数中会为新的 `_defer` 设置一些基础属性，并将调用函数的参数集传入。最后通过特殊的返回方法结束函数调用**。另外这一块与先前 [《深入理解 Go panic and recover》](https://segmentfault.com/a/1190000019251478#articleHeader9) 的处理逻辑有一定关联性，其实就是 `gp.sched.ret` 返回 0 还是 1 会分流至不同处理方式

### newdefer

```go
func newdefer(siz int32) *_defer {
	var d *_defer
	sc := deferclass(uintptr(siz))
	gp := getg()
	if sc < uintptr(len(p{}.deferpool)) {
		pp := gp.m.p.ptr()
		if len(pp.deferpool[sc]) == 0 && sched.deferpool[sc] != nil {
			...
			lock(&sched.deferlock)
			d := sched.deferpool[sc]
			unlock(&sched.deferlock)
		}
		...
	}
	if d == nil {
		systemstack(func() {
			total := roundupsize(totaldefersize(uintptr(siz)))
			d = (*_defer)(mallocgc(total, deferType, true))
		})
		...
	}
	d.siz = siz
	d.link = gp._defer
	gp._defer = d
	return d
}
```

- 从池中获取可以使用的 `_defer`，则复用作为新的基础单元
- 若在池中没有获取到可用的，则调用 `mallocgc` 重新申请一个新的
- 设置 `defer` 的基础属性，最后修改当前 `Goroutine` 的 `_defer` 指向

通过这个方法我们可以注意到两点，如下：

- `defer` 与 `Goroutine(g)` 有直接关系，所以讨论 `defer` 时基本离不开 `g` 的关联
- 新的 `defer` 总是会在现有的链表中的最前面，也就是 `defer` 的特性后进先出

#### 小结

这个函数主要承担了获取新的 `_defer` 的作用，它有可能是从 `deferpool` 中获取的，也有可能是重新申请的

### deferreturn

```go
func deferreturn(arg0 uintptr) {
	gp := getg()
	d := gp._defer
	if d == nil {
		return
	}
	sp := getcallersp()
	if d.sp != sp {
		return
	}

	switch d.siz {
	case 0:
		// Do nothing.
	case sys.PtrSize:
		*(*uintptr)(unsafe.Pointer(&arg0)) = *(*uintptr)(deferArgs(d))
	default:
		memmove(unsafe.Pointer(&arg0), deferArgs(d), uintptr(d.siz))
	}
	fn := d.fn
	d.fn = nil
	gp._defer = d.link
	freedefer(d)
	jmpdefer(fn, uintptr(unsafe.Pointer(&arg0)))
}
```

如果在一个方法中调用过 `defer` 关键字，那么编译器将会在结尾处插入 `deferreturn` 方法的调用。而该方法中主要做了如下事项：

- 清空当前节点 `_defer` 被调用的函数调用信息
- 释放当前节点的 `_defer` 的存储信息并放回池中（便于复用）
- 跳转到调用 `defer` 关键字的调用函数处

在这段代码中，跳转方法 `jmpdefer` 格外重要。因为它显式的控制了流转，代码如下：

```
// asm_amd64.s
TEXT runtime·jmpdefer(SB), NOSPLIT, $0-16
	MOVQ	fv+0(FP), DX	// fn
	MOVQ	argp+8(FP), BX	// caller sp
	LEAQ	-8(BX), SP	// caller sp after CALL
	MOVQ	-8(SP), BP	// restore BP as if deferreturn returned (harmless if framepointers not in use)
	SUBQ	$5, (SP)	// return to CALL again
	MOVQ	0(DX), BX
	JMP	BX	// but first run the deferred function
```

通过源码的分析，我们发现它做了两个很 “奇怪” 又很重要的事，如下：

- MOVQ -8(SP), BP：`-8(BX)` 这个位置保存的是 `deferreturn` 执行完毕后的地址
- SUBQ \$5, (SP)：`SP` 的地址减 5 ，其减掉的长度就恰好是 `runtime.deferreturn` 的长度

你可能会问，为什么是 5？好吧。翻了半天最后看了一下汇编代码...嗯，相减的确是 5 没毛病，如下：

```
	0x007a 00122 (main.go:7)	CALL	runtime.deferreturn(SB)
	0x007f 00127 (main.go:7)	MOVQ	56(SP), BP
```

我们整理一下思绪，照上述逻辑的话，那 `deferreturn` 就是一个 “递归” 了哦。每次都会重新回到 `deferreturn` 函数，那它在什么时候才会结束呢，如下：

```go
func deferreturn(arg0 uintptr) {
	gp := getg()
	d := gp._defer
	if d == nil {
		return
	}
	...
}
```

也就是会不断地进入 `deferreturn` 函数，判断链表中是否还存着 `_defer`。若已经不存在了，则返回，结束掉它。简单来讲，就是处理完全部 `defer` 才允许你真的离开它。果真如此吗？我们再看看上面的汇编代码，如下：

```
    。..
	0x0070 00112 (main.go:6)	CALL	runtime.deferproc(SB)
	0x0075 00117 (main.go:6)	TESTL	AX, AX
	0x0077 00119 (main.go:6)	JNE	137
	0x0079 00121 (main.go:7)	XCHGL	AX, AX
	0x007a 00122 (main.go:7)	CALL	runtime.deferreturn(SB)
	0x007f 00127 (main.go:7)	MOVQ	56(SP), BP
	0x0084 00132 (main.go:7)	ADDQ	$64, SP
	0x0088 00136 (main.go:7)	RET
	0x0089 00137 (main.go:6)	XCHGL	AX, AX
	0x008a 00138 (main.go:6)	CALL	runtime.deferreturn(SB)
	...
```

的确如上述流程所分析一致，验证完毕

#### 小结

这个函数主要承担了清空已使用的 `defer` 和跳转到调用 `defer` 关键字的函数处，非常重要

## 总结

我们有提到 `defer` 关键字涉及两个核心的函数，分别是 `deferproc` 和 `deferreturn` 函数。而 `deferreturn` 函数比较特殊，是当应用函数调用 `defer` 关键字时，编译器会在其结尾处插入 `deferreturn` 的调用，它们俩一般都是成对出现的

但是当一个 `Goroutine` 上存在着多次 `defer` 行为（也就是多个 `_defer`）时，编译器会进行利用一些小技巧， 重新回到 `deferreturn` 函数去消耗 `_defer` 链表，直到一个不剩才允许真正的结束

而新增的基础单元 `_defer`，有可能是被复用的，也有可能是全新申请的。它最后都会被追加到 `_defer` 链表的表头，从而设定了后进先出的调用特性

## 关联

- [深入理解 Go panic and recover](https://github.com/EDDYCJY/blog/blob/master/golang/pkg/2019-05-18-%E6%B7%B1%E5%85%A5%E7%90%86%E8%A7%A3Go-panic-and-recover.md)

## 参考

- [Scheduling In Go](https://www.ardanlabs.com/blog/2018/08/scheduling-in-go-part1.html)
- [Dive into stack and defer/panic/recover in go](http://hustcat.github.io/dive-into-stack-defer-panic-recover-in-go/)
- [golang-notes](https://github.com/cch123/golang-notes/blob/master/defer.md)


================================================
FILE: content/posts/go/delve.md
================================================
---
title: "一个 Demo 学会使用 Go Delve 调试"
date: 2021-12-31T12:54:57+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在 Go 语言中，除了 go tool 工具链中的 pprof、trace 等剖析工具的大利器外。常常还会有小伙伴问，有没有更好用，更精细的，

大家总嫌弃 pprof、trace 等工具，不够细，没法一口气看到根因，或者具体变量...希望能够最好能追到代码级别调试的，看到具体变量的值是怎么样的，随意想怎么看怎么看的那种。

为此今天给大家介绍 Go 语言强大的 Delve （dlv）调试工具，来更深入问题剖析。

## 安装

我们需要先安装 Go delve，若是 Go1.16 及以后的版本，可以直接执行下述命令安装：

```
$ go install github.com/go-delve/delve/cmd/dlv@latest
```

也可以通过 git clone 的方式安装：

```
$ git clone https://github.com/go-delve/delve
$ cd delve
$ go install github.com/go-delve/delve/cmd/dlv
```

在安装完毕后，我们执行 `dlv version` 命令，查看安装情况：

```
$ dlv version
Delve Debugger
Version: 1.7.0
Build: $Id: e353a65161e6ed74952b96bbb62ebfc56090832b $
```

可以明确看到我们所安装的版本是 v1.7.0。

## 演示程序

我们计划用一个反转字符串的演示程序来进行 Go 程序的调试。第一部分先是完成 `stringer` 包的 `Reverse` 方法。

代码如下：

```golang
package stringer

func Reverse(s string) string {
	r := []rune(s)
	for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
		r[i], r[j] = r[j], r[i]
	}
	return string(r)
}
```

再在具体的 `main` 启动函数中进行调用。代码如下：

```golang
import (
	"fmt"

	"github.com/eddycjy/awesome-project/stringer"
)

func main() {
	fmt.Println(stringer.Reverse("脑子进煎鱼了！"))
}
```

输出结果：

```
！了鱼煎进子脑
```

## 进行调试

Delve 是 Go 程序的源代码级调试器。Delve 使您能够通过控制流程的执行与您的程序进行交互，查看变量，提供线程、goroutine、CPU 状态等信息。

其一共支持如下 11 个子命令：

```
Available Commands:
  attach      Attach to running process and begin debugging.
  connect     Connect to a headless debug server.
  core        Examine a core dump.
  dap         [EXPERIMENTAL] Starts a TCP server communicating via Debug Adaptor Protocol (DAP).
  debug       Compile and begin debugging main package in current directory, or the package specified.
  exec        Execute a precompiled binary, and begin a debug session.
  help        Help about any command
  run         Deprecated command. Use 'debug' instead.
  test        Compile test binary and begin debugging program.
  trace       Compile and begin tracing program.
  version     Prints version.
```

我们今天主要用到的是 debug 命令，他能够编译并开始调试当前目录下的主包，或指定的包，是最常用的功能之一。

接下来我们利用这个演示程序来进行 dlv 的深入调试和应用。

执行如下命令：

```
➜  awesomeProject dlv debug .
Type 'help' for list of commands.
(dlv) 
```

我们先在演示程序根目录下执行了 debug，进入了 dlv 的交互模式。

再使用关键字 `b`（break 的缩写）对 `main.main` 方法设置断点：

```
(dlv) b main.main
Breakpoint 1 (enabled) set at 0x10cbab3 for main.main() ./main.go:9
(dlv) 
```

设置完毕后，我们可以看到方法对应的文件名、行数。接着我们可以执行关键字 `c`（continue 的缩写）跳转到下一个断点处：

```
(dlv) c
> main.main() ./main.go:9 (hits goroutine(1):1 total:1) (PC: 0x10cbab3)
     4:		"fmt"
     5:	
     6:		"github.com/eddycjy/awesome-project/stringer"
     7:	)
     8:	
=>   9:	func main() {
    10:		fmt.Println(stringer.Reverse("脑子进煎鱼了！"))
    11:	}
(dlv) 
```

在断点处，我看可以看到具体的代码块、goroutine、CPU 寄存器地址等运行时信息。

紧接着执行关键字 `n`（next 的缩写）单步执行程序的下一步：

```
(dlv) n
> main.main() ./main.go:10 (PC: 0x10cbac1)
     5:	
     6:		"github.com/eddycjy/awesome-project/stringer"
     7:	)
     8:	
     9:	func main() {
=>  10:		fmt.Println(stringer.Reverse("脑子进煎鱼了！"))
    11:	}
```

我们可以看到程序走到了 main.go 文件中的第 10 行中，并且调用了 `stringer.Reverse` 方法去处理。

此时我们可以执行关键字 `s`（step 的关键字）进入到这个函数中去继续调试：

```
(dlv) s
> github.com/eddycjy/awesome-project/stringer.Reverse() ./stringer/string.go:3 (PC: 0x10cb87b)
     1:	package stringer
     2:	
=>   3:	func Reverse(s string) string {
     4:		r := []rune(s)
     5:		for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
     6:			r[i], r[j] = r[j], r[i]
     7:		}
     8:		return string(r)
```

输入后，调试的光标会到 `Reverse` 方法上，此时我们可以调用关键字 `p`（print 的缩写）传出所传入的变量的值：

```
(dlv) p s
"脑子进煎鱼了！"
```

此处函数的形参变量是 s，输出了 “脑子进煎鱼了！”，与我们所传入的是一致的。

但故事一般没有这么的简单，会用到 Delve 来调试，说明是比较细致、隐患的 BUG。为此我们大多需要更进一步的深入。

我们继续围观 `Reverse` 方法：

```
     5:		for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
     6:			r[i], r[j] = r[j], r[i]
     7:		}
```

从表现来看，我们常常会怀疑是第 6 行可能是问题的所在。这时可以针对性的对第 6 行进行断点查看：

```
(dlv) b 6
Breakpoint 2 (enabled) set at 0x10cb92c for github.com/eddycjy/awesome-project/stringer.Reverse() ./stringer/string.go:6
```

设置完断点后，我们只需要执行关键字 `c`，继续下一步：

```
(dlv) c
> github.com/eddycjy/awesome-project/stringer.Reverse() ./stringer/string.go:6 (hits goroutine(1):1 total:1) (PC: 0x10cb92c)
     1:	package stringer
     2:	
     3:	func Reverse(s string) string {
     4:		r := []rune(s)
     5:		for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
=>   6:			r[i], r[j] = r[j], r[i]
     7:		}
     8:		return string(r)
     9:	}
```

走到对应的代码片段后，执行关键字 `locals`：

```
(dlv) locals
r = []int32 len: 7, cap: 32, [...]
j = 6
i = 0
```

我们就可以看到对应的变量 r, i, j 的值是多少，可以根据此来分析程序流转是否与我们预想的一致。

另外也可以调用关键字 `set` 去针对特定变量设置期望的值：

```
(dlv) set i = 1
(dlv) locals
r = []int32 len: 7, cap: 32, [...]
j = 6
i = 1
```

设置后，若还需要继续排查，可以继续调用关键字 `c` 去定位，这种常用于特定变量的特定值的异常，这样一设置一调试基本就能排查出来了。

在排查完毕后，我们可以执行关键字 `r`（reset 的缩写）：

```
(dlv)  r
Process restarted with PID 56614
```

执行完毕后，整个调试就会重置，像是前面在打断点时所设置的变量值就会恢复。

若要查看设置的断点情况，也可以执行关键字 `bp` 查看：

```
(dlv) bp
Breakpoint runtime-fatal-throw (enabled) at 0x1038fc0 for runtime.fatalthrow() /usr/local/Cellar/go/1.16.2/libexec/src/runtime/panic.go:1163 (0)
Breakpoint unrecovered-panic (enabled) at 0x1039040 for runtime.fatalpanic() /usr/local/Cellar/go/1.16.2/libexec/src/runtime/panic.go:1190 (0)
	print runtime.curg._panic.arg
Breakpoint 1 (enabled) at 0x10cbab3 for main.main() ./main.go:9 (0)
Breakpoint 2 (enabled) at 0x10cb92c for github.com/eddycjy/awesome-project/stringer.Reverse() ./stringer/string.go:6 (0)
```

查看断点情况后，若有部分已经排除了，可以调用关键字 `clearall` 对一些断点清除：

```
(dlv) clearall main.main
Breakpoint 1 (enabled) cleared at 0x10cbab3 for main.main() ./main.go:9
```

若不指点断点，则会默认清除全部断点。

在日常的 Go 工程中，若都从 main 方法进入就太繁琐了。我们可以直接借助函数名进行调式定位：

```
(dlv) funcs Reverse
github.com/eddycjy/awesome-project/stringer.Reverse
(dlv) b stringer.Reverse
Breakpoint 3 (enabled) set at 0x10cb87b for github.com/eddycjy/awesome-project/stringer.Reverse() ./stringer/string.go:3
(dlv) c
> github.com/eddycjy/awesome-project/stringer.Reverse() ./stringer/string.go:3 (hits goroutine(1):1 total:1) (PC: 0x10cb87b)
     1:	package stringer
     2:	
=>   3:	func Reverse(s string) string {
     4:		r := []rune(s)
     5:		for i, j := 0, len(r)-1; i < len(r)/2; i, j = i+1, j-1 {
     6:			r[i], r[j] = r[j], r[i]
     7:		}
     8:		return string(r)
```

紧接着其他步骤都与先前的一样，进行具体的调试就好了。我们也可以借助 Go 语言的公共函数进行计算：

```
(dlv) p len(r)-1
6
```

也可以借助关键字 `vars` 查看某个包下的所有全局变量的值，例如：`vars main`。这种方式对于查看全局变量的情况非常有帮助。

排查完毕后，执行关键字 `exit` 就可以愉快的退出了：

```
(dlv) exit
```

解决完问题，可以下班了 ：）

## 总结

在 Go 语言中，Delve 调试工具是与 Go 语言亲和度最高的，因为 Delve 是 Go 语言实现的。其在我们日常工作中，非常常用。

像是假设程序的 for 循环运行到第 N 次才出现 BUG 时，我们就可以通过断点对应的方法和代码块，再设置变量的值，进行具体的查看，就可以解决。



================================================
FILE: content/posts/go/empty-struct.md
================================================
---
title: "详解 Go 空结构体的 3 种使用场景"
date: 2021-12-31T12:54:51+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在大家初识 Go 语言时，总会拿其他语言的基本特性来类比 Go 语言，说白了就是老知识和新知识产生关联，实现更高的学习效率。

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/87c66858abf04b848643b6fa03f4bdab~tplv-k3u1fbpfcp-zoom-1.image)

最常见的类比，就是 “Go 语言如何实现面向对象？”，进一步展开就是 Go 语言如何实现面向对象特性中的继承。

这不仅在学习中才用到类比，在业内的 Go 面试中也有非常多的面试官喜欢问：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d1cc9c2b2e174fc4a82506b368591a70~tplv-k3u1fbpfcp-zoom-1.image)

来自读者微信群

在今天这篇文章中，煎鱼带大家具体展开了解这块的知识。一起愉快地开始吸鱼之路。

什么是面向对象
-------

在了解 Go 语言是不是面向对象（简称：OOP） 之前，我们必须先知道 OOP 是啥，得先给他 “下定义”。

根据 Wikipedia 的定义，我们梳理出 OOP 的几个基本认知：

*   面向对象编程（OOP）是一种基于 "对象" 概念的编程范式，它可以包含数据和代码：数据以字段的形式存在（通常称为属性或属性），代码以程序的形式存在（通常称为方法）。
    
*   对象自己的程序可以访问并经常修改自己的数据字段。
    
*   对象经常被定义为类的一个实例。
    
*   对象利用属性和方法的私有/受保护/公共可见性，对象的内部状态受到保护，不受外界影响（被封装）。
    

基于这几个基本认知进行一步延伸出，面向对象的三大基本特性：

*   封装。
    
*   继承。
    
*   多态。
    

至此对面向对象的基本概念讲解结束，想更进一步了解的可自行网上冲浪。

Go 是面向对象的语言吗
------------

“Go 语言是否一门面向对象的语言？”，这是一个日经话题。官方 FAQ 给出的答复是：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/bb8296e58a6d4c7c882984dcceaaf9c0~tplv-k3u1fbpfcp-zoom-1.image)

是的，也不是。原因是：

*   Go 有类型和方法，并且允许面向对象的编程风格，但没有类型层次。
    
*   Go 中的 "接口 "概念提供了一种不同的方法，我们认为这种方法易于使用，而且在某些方面更加通用。还有一些方法可以将类型嵌入到其他类型中，以提供类似的东西，但不等同于子类。
    
*   Go 中的方法比 C++ 或 Java 中的方法更通用：它们可以为任何类型的数据定义，甚至是内置类型，如普通的、"未装箱的 "整数。它们并不局限于结构（类）。
    
*   Go 由于缺乏类型层次，Go 中的 "对象 "比 C++ 或 Java 等语言更轻巧。
    

Go 实现面向对象编程
-----------

### 封装

面向对象中的 “封装” 指的是可以隐藏对象的内部属性和实现细节，仅对外提供公开接口调用，这样子用户就不需要关注你内部是怎么实现的。

在 Go 语言中的属性访问权限，通过首字母大小写来控制：

*   首字母大写，代表是公共的、可被外部访问的。
    
*   首字母小写，代表是私有的，不可以被外部访问。
    

Go 语言的例子如下：

```
type Animal struct {
 name string
}

func NewAnimal() *Animal {
 return &Animal{}
}

func (p *Animal) SetName(name string) {
 p.name = name
}

func (p *Animal) GetName() string {
 return p.name
}

```

在上述例子中，我们声明了一个结构体 `Animal`，其属性 `name` 为小写。没法通过外部方法，在配套上存在 Setter 和 Getter 的方法，用于统一的访问和设置控制。

以此实现在 Go 语言中的基本封装。

### 继承

面向对象中的 “继承” 指的是子类继承父类的特征和行为，使得子类对象（实例）具有父类的实例域和方法，或子类从父类继承方法，使得子类具有父类相同的行为。

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ec1cf116a1bf404981cb624009945157~tplv-k3u1fbpfcp-zoom-1.image)

图来自网络

从实际的例子来看，就是动物是一个大父类，下面又能细分为 “食草动物”、“食肉动物”，这两者会包含 “动物” 这个父类的基本定义。

在 Go 语言中，是没有类似 `extends` 关键字的这种继承的方式，在语言设计上采取的是组合的方式：

```
type Animal struct {
 Name string
}

type Cat struct {
 Animal
 FeatureA string
}

type Dog struct {
 Animal
 FeatureB string
}

```

在上述例子中，我们声明了 `Cat` 和 `Dog` 结构体，其在内部匿名组合了 `Animal` 结构体。因此 `Cat` 和 `Dog` 的实例都可以调用 `Animal` 结构体的方法：

```
func main() {
 p := NewAnimal()
 p.SetName("煎鱼，记得点赞~")

 dog := Dog{Animal: *p}
 fmt.Println(dog.GetName())
}

```

同时 `Cat` 和 `Dog` 的实例可以拥有自己的方法：

```
func (dog *Dog) HelloWorld() {
 fmt.Println("脑子进煎鱼了")
}

func (cat *Cat) HelloWorld() {
 fmt.Println("煎鱼进脑子了")
}

```

上述例子能够正常包含调用 `Animal` 的相关属性和方法，也能够拥有自己的独立属性和方法，在 Go 语言中达到了类似继承的效果。

### 多态

面向对象中的 “多态” 指的同一个行为具有多种不同表现形式或形态的能力，具体是指一个类实例（对象）的相同方法在不同情形有不同表现形式。

多态也使得不同内部结构的对象可以共享相同的外部接口，也就是都是一套外部模板，内部实际是什么，只要符合规格就可以。

在 Go 语言中，多态是通过接口来实现的：

```
type AnimalSounder interface {
 MakeDNA()
}

func MakeSomeDNA(animalSounder AnimalSounder) {
 animalSounder.MakeDNA()
}

```

在上述例子中，我们声明了一个接口类型 `AnimalSounder`，配套一个 `MakeSomeDNA` 方法，其接受 `AnimalSounder` 接口类型作为入参。

因此在 Go 语言中。只要配套的 `Cat` 和 `Dog` 的实例也实现了 `MakeSomeDNA` 方法，那么我们就可以认为他是 `AnimalSounder` 接口类型：

```
type AnimalSounder interface {
 MakeDNA()
}

func MakeSomeDNA(animalSounder AnimalSounder) {
 animalSounder.MakeDNA()
}

func (c *Cat) MakeDNA() {
 fmt.Println("煎鱼是煎鱼")
}

func (c *Dog) MakeDNA() {
 fmt.Println("煎鱼其实不是煎鱼")
}

func main() {
 MakeSomeDNA(&Cat{})
 MakeSomeDNA(&Dog{})
}

```

当 `Cat` 和 `Dog` 的实例实现了 `AnimalSounder` 接口类型的约束后，就意味着满足了条件，他们在 Go 语言中就是一个东西。能够作为入参传入 `MakeSomeDNA` 方法中，再根据不同的实例实现多态行为。

总结
--

通过今天这篇文章，我们基本了解了面向对象的定义和 Go 官方对面向对象这一件事的看法，同时针对面向对象的三大特性：“封装、继承、多态” 在 Go 语言中的实现方法就进行了一一讲解。

在日常工作中，基本了解这些概念就可以了。若是面试，可以针对三大特性：“封装、继承、多态” 和 五大原则 “单一职责原则（SRP）、开放封闭原则（OCP）、里氏替换原则（LSP）、依赖倒置原则（DIP）、接口隔离原则（ISP）” 进行深入理解和说明。

在说明后针对上述提到的概念。再在 Go 语言中讲解其具体的实现和利用到的基本原理，互相结合讲解，就能得到一个不错的效果了。

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，欢迎 Star 催更。


参考
--

*   Is Go an Object Oriented language?
    
*   面向对象的三大基本特征，五大基本原则
    
*   Go 面向对象编程（译）

================================================
FILE: content/posts/go/enum.md
================================================
---
title: "小技巧分享：在 Go 如何实现枚举？"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在日常的业务工程开发中，我们常常会有使用枚举值的诉求，枚举控的好，测试值边界一遍过...

有的小伙伴会说，在 Go 语言不是有 `iota` 类型做枚举吗，那煎鱼你这篇文章还讲什么？

讲道理，Go 语言并没有 enum 关键字，有用过 Protobuf 等的小伙伴知道，Go 语言只是 ”有限的枚举“ 支持，我们也会用常量来定义，枚举值也需要有字面意思的映射。

示例
--

在一些业务场景下，是没法达到我们的诉求的。示例如下：

```
type FishType int

const (
 A FishType = iota
 B
 C
 D
)

func main() {
 fmt.Println(A, B, C, D)
}
```

输出结果为：“0 1 2 3”。这时候就一脸懵逼了...枚举值，应该除了键以外，还得有个对应的值。也就是这个 “0 1 2 3” 分别对应着什么含义，是不是应该输出 ”A B C D“

但 Go 语言这块就没有直接的支撑了，因此这不是一个完整的枚举类型的实现。

同时假设我们传入超过 `FishType` 类型声明范围的枚举值，在 Go 语言中默认也不会有任何控制，是正常输出的。

上述这种 Go 枚举实现，在某种情况下是不完全的，严格意义上不能成为 enum（枚举）。

使用 String 做枚举
-------------

如果要支持枚举值的对应输出的话，我们可以通过如下方式：

```
type FishType int

const (
 A FishType = iota
 B
 C
 D
)

func (f FishType) String() string {
 return [...]string{"A", "B", "C", "D"}[f]
}
```

运行程序：

```
func main() {
 var f FishType = A
 fmt.Println(f)
 switch f {
 case A:
  fmt.Println("脑子进煎鱼了")
 case B:
  fmt.Println("记得点赞")
 default:
  fmt.Println("别别别...")
 }
}
```

输出结果：

```
A
脑子进煎鱼了
```

我们可以借助 Go 中 `String` 方法的默认约定，针对于定义了 `String` 方法的类型，默认输出的时候会调用该方法。

这样就可以达到获得枚举值的同时，也能拿到其映射的字面意思。

自动生成 String
-----------

但每次手动编写还是比较麻烦的。在这一块，我们可以利用官方提供的 `cmd/string` 来快速实现。

我们安装如下命令：

```
go install golang.org/x/tools/cmd/stringer
```

在所需枚举值上设置 `go:generate` 指令：

```
//go:generate stringer -type=FishType
type FishType int
```

在项目根目录执行：

```
go generate ./...

```

会在根目录生成 fishtype\_string.go 文件：

```
.
├── fishtype_string.go
├── go.mod
├── go.sum
└── main.go
```

fishtype\_string 文件内容：

```
package main

import "strconv"

const _FishType_name = "ABCD"

var _FishType_index = [...]uint8{0, 1, 2, 3, 4}

func (i FishType) String() string {
 if i < 0 || i >= FishType(len(_FishType_index)-1) {
  return "FishType(" + strconv.FormatInt(int64(i), 10) + ")"
 }
 return _FishType_name[_FishType_index[i]:_FishType_index[i+1]]
}
```

所生成出来的文件，主要是根据枚举值和映射值做了个映射，且针对超出枚举值的场景进行了判断：

```
func main() {
 var f1 FishType = A
 fmt.Println(f1)
 var f2 FishType = E
 fmt.Println(f2)
}
```

执行 `go run .` 查看程序运行结果：

```
$ go run .
A
FishType(4)
```

总结
--

在今天这篇文章中，我们介绍了如何在 Go 语言实现标准的枚举值，虽然有些繁琐，但整体不会太难。

![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/05d5614987b04e0183e20fb5ac5249d4~tplv-k3u1fbpfcp-zoom-1.image)

也有小伙伴已经在社区中提出了 ”proposal: spec: add typed enum support“ 的提案，相信未来有机会能看到 Go 自身支持 enum（枚举）的那一天。

你平时会怎么在业务代码中实现枚举呢，欢迎大家一起留言交流：）


**欢迎大家在评论区留言和交流 ：）**

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，学习 Go 语言可以看 [Go 学习地图和路线](https://github.com/eddycjy/go-developer-roadmap)，欢迎 Star 催更。

================================================
FILE: content/posts/go/func-reload.md
================================================
---
title: "Go 为什么不支持函数重载和参数默认值？"
date: 2021-12-31T12:55:16+08:00
toc: true
images:
tags: 
  - go
  - 为什么
---

大家好，我是煎鱼。

大家在初学习 Go 语言时，带着其他语言的习惯，总是会有些不习惯，感觉非常不能理解，直打问号。

其中一点就是 Go 语言不支持函数重载和参数默认值，觉得使用起来很不方便。

为此，在这篇文章中煎鱼就和大家一起来了解为什么，有又会怎么样。

## 函数重载

函数重载（function overloading），也叫方法重载。是某些编程语言（如 C++、C#、Java、Swift、Kotlin 等）具有的一项特性。

该特性**允许创建多个具有不同实现的同名函数**，对重载函数的调用会运行其适用于调用上下文的具体实现。

从功能上来讲，就是允许一个函数调用根据上下文执行不同的方法，达到调用同一个函数名，执行不同的方法。

一个简单的例子：

```c++
#include <iostream>

int Volume(int s) {  // 立方体的体积。
  return s * s * s;
}

double Volume(double r, int h) {  // 圆柱体的体积。
  return 3.1415926 * r * r * static_cast<double>(h);
}

long Volume(long l, int b, int h) {  // 长方体的体积。
  return l * b * h;
}

int main() {
  std::cout << Volume(10);
  std::cout << Volume(2.5, 8);
  std::cout << Volume(100l, 75, 15);
}
```

在上述例子中，实现了 3 个同名的 `Volume` 函数，但是 3 个函数的入参个数、类型均不一样，也代表了不同的实现目的。

在主函数 `main` 中，传入了不同的入参，编译器或运行时再进行内部处理，从程序上来看达到了调用不同函数的目的。

这就是函数重载，一函数多形态。

## 参数默认值

参数默认值，又叫缺省参数。指的是允许程序员设定缺省参数并指定默认值，**当调用该函数并未指定值时，该缺省参数将为缺省值来使用**。

一个简单的例子：

```c++
 int my_func(int a, int b, int c=12);
```

在上述例子中，函数 `my_func` 一共有 3 个变量，分别是：a、b、c。变量 c 设置了缺省值，也就是 12。

其调用方式可以为：

```c++
 // 第一种调用方式
 result = my_func(1, 2, 3);
 // 第二种调用方式
 result = my_func(1, 2);
```

在第一种方式中，就会正常的传入所有参数。在第二种方式，由于第三个参数 c 并没有传递，因此会直接使用缺省值 12。

这就是参数默认值，也叫缺省参数。

## 为什么不支持

### 美好

从上述的功能特性介绍来看，似乎非常的不错，能够节省很多功夫。像是 Go 语言的 context 库中的这些方法：

```golang
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
```

要是有函数重载，直接就 WithXXX 就好了，只需要关注传入的参数类型，也不用 “记” 那么多个方法名了。

有同学说，有参数默认值。那就可以直接设置在上面，作为 “最佳实践” 给到使用函数的人，岂不美哉。那怎么 Go 语言就不支持呢？

### 细思

其实这和设计理念，和对程序的理解有关系。说白了，就是你喜欢 “显式”，还是 “隐喻”。

函数重载和参数默认值，其实是不好的行为。调用者只看函数名字，可能没法知道，你这个默认值，又或是入参不同，会调用的东西，会产生怎么样的后果？

你可以观察一下自己的行为。大部分人都会潜意识的追进去看代码，看看会调到哪，缺省值的作用是什么，以确保可控。

### 敲定

这细思的可能，在 Go 语言中是不被允许的。Go 语言的**设计理念就是 “显式大于隐喻”，追求明确，显式**。

在 Go FAQ 《Why does Go not support overloading of methods and operators?》有相关的解释。

如下图：

![](https://files.mdnice.com/user/3610/582eac4e-ecd1-4fb5-bde7-b2cbcac7f809.png)

官方有明确提到两个观点：
- 函数重载：拥有各种同名但不同签名的方法有时是很有用的，但在实践中也可能是混乱和脆弱的。
- 参数默认值：操作符重载，似乎更像是一种便利，不是绝对的要求。没有它，程序会更简单。

这就是为什么 Go 语言不支持的原因。

## 总结

在这篇文章中，我们介绍了业内常见的编程语言的函数重载和参数默认值的概念和使用方法。也结合了 Go 语言自身的设计理念，说明了为什么不支持的原因。

你会希望 Go 语言支持这几个特性功能吗，欢迎在评论区留言讨论和交流：）

## 参考

- 维基百科（函数重载和缺省值定义）
- Frequently Asked Questions (FAQ)

================================================
FILE: content/posts/go/fuzzing.md
================================================
---
title: "提高 Go 程序健壮性，Fuzzing 要来了！"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

就在前几天，Go1.17 beta1 正式发布：

![](https://files.mdnice.com/user/3610/fb4ceb3d-ef1c-4c32-a7c3-a4188a0d74b0.png)

兴冲冲本想着看一下当初在 Go1.17 的计划中，预计会支持的新特性：模糊测试（Fuzzing）。不过没想到...计划赶不上变化，官方正式宣告 Fuzzing 不会出现在 Go1.17 的新功能中。

煎鱼在悲伤之际，发现 Go 在 dev.fuzz 分支上提供了该功能的 Beta 测试，因此今天带大家一起来深入该特性。

## 什么是 Fuzzing

Fuzzing 是一种自动测试技术，包括向计算机程序提供随机数据作为输入。然后监测程序是否出现恐慌、断言失败、无限循环等。

Fuzzing 不是使用一个小的、预先定义好的手动创建的输入集（如单元测试），而是用新的案例不断地测试代码，以努力 ”锻炼“ 有关软件的所有方面。

这听起来很 ”难“。但在过去的几年里，Fuzzing 的技术水平有了很大的提高。Fuzzing 不再是需要专业知识才能成功使用的东西，现代模糊测试策略能更快、更有效地找到有用的输入。

在应用程序中，就是你只要引入一个 package，对着 API 一顿用就可以了。

## 为什么要做 Fuzzing

可能会有小伙伴说，测试？直接人工测试，再把测试数据准备一下，配套 YAPI 等接口管理平台，把自动化接口测试一弄就好了。还需要 Fuzzing 吗？

其实 Fuzzing 是对其他形式的测试、代码审查和静态分析的补充，它通过生成一个随机测试用例去覆盖人为测不到的各种复杂场景。而这些输入几乎不可能人为去构造，总会被传统测试所遗漏。

## 发生在身边的 Fuzzing

实际上 Go-fuzz 对 Go 标准库进行过测试，依然这这之中发现了 200  多个 bug：

![](https://files.mdnice.com/user/3610/9b00972c-2231-4406-84b8-2e8e44f57d6d.png)

这还是建立在标准库已经比较成熟，且由非常有经验的开发者编写，在生产中使用多年的情况下，依然有如此多的问题。

## 快速上手

我们需要在本地执行如下命令，需开启 GO111MODULE 和天梯：

```golang
$ go get golang.org/dl/gotip
$ gotip download dev.fuzz
```

执行完毕后会从 dev.fuzz 分支构建 Go 工具链，同时 gotip 可以作为 go 命令的替代者命令，也就是可以运行 Fuzzing 的相关代码了。

```golang
// +build gofuzzbeta

package tests

import (
	"net/url"
	"reflect"
	"testing"
)

func FuzzParseQuery(f *testing.F) {
	f.Add("x=1&y=2")
	f.Fuzz(func(t *testing.T, queryStr string) {
		query, err := url.ParseQuery(queryStr)
		if err != nil {
			t.Skip()
		}
		queryStr2 := query.Encode()
		query2, err := url.ParseQuery(queryStr2)
		if err != nil {
			t.Fatalf("ParseQuery failed to decode a valid encoded query %s: %v", queryStr2, err)
		}
		if !reflect.DeepEqual(query, query2) {
			t.Errorf("ParseQuery gave different query after being encoded\nbefore: %v\nafter: %v", query, query2)
		}
	})
}
```

在相应的目录下执行 `gotip test -fuzz=FuzzParseQuery` 命令，输出结果：

```golang
fuzzing, elapsed: 3.0s, execs: 319 (106/sec), workers: 4, interesting: 15
fuzzing, elapsed: 6.0s, execs: 665 (111/sec), workers: 4, interesting: 15
fuzzing, elapsed: 9.0s, execs: 1019 (113/sec), workers: 4, interesting: 15
fuzzing, elapsed: 12.0s, execs: 1400 (117/sec), workers: 4, interesting: 15
...
```

需要注意的是：
- Fuzzing 会消耗大量的内存，在运行时会影响到机器的性能（一运行，小风扇就转了起来）。
- Fuzzing 会默认使用 `GOMAXPROCS`相同的核数，可以通过执行 `-parallel` 标识来控制数量。
- Fuzzing 会默认在运行时，将扩大测试范围的数值写入 `$GOCACHE/fuzz` 内的模糊缓存目录，目前是没有限制的，可以通过运行 `gotip clean -fuzzcache` 来清除。

## 总结

在今天这篇文章中，我们介绍了 Fuzzing 是什么。
简单而言，模糊测试（Fuzzing）在真实环境已经被验证了其有效性，其可以随机生成测试用例去覆盖人为测不到的各种复杂场景，带来很大的收益。

在接下来中，除了依赖开源的 go-fuzz 库外，Go 语言也正式的在支持 Fuzzing，虽然他放了 Go1.17 的鸽子...

这会对构建 Go 程序健壮性的又一强心剂！

================================================
FILE: content/posts/go/gdb.md
================================================
---
title: "学会使用 GDB 调试 Go 代码"
date: 2021-12-31T12:54:57+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

上一篇文章《一个 Demo 学会使用 Go Delve 调试》我们详细介绍了 Go 语言如何使用 Delve 进行排查和调试，对于问题的解决非常的有帮助。

但调试工具肯定不止只有 Delve，今天我们来介绍第二个神器，那就是：GDB。

## GDB 是什么

GDB 是一个类 UNIX 系统下的程序调试工具，允许你看到另一个程序在执行时 "内部 "发生了什么，或者程序在崩溃时正在做什么。

![GDB Logo](https://files.mdnice.com/user/3610/35fc6475-ec0d-44a0-ae8c-920121130edb.png)

主要可以做四类事情：

1. 启动你的程序，指定任何可能影响其行为的东西。
2. 使你的程序在指定的条件下停止。
3. 检查当你的程序停止时发生了什么。
4. 改变你程序中的东西，这样你就可以试验纠正一个错误的影响，并继续了解另一个错误。

## 安装

如果是在 MacOS 上的话，可以直接使用 brew 安装：

```
brew install gdb
```

如果是在 Linux ，则使用自带的包管理工具进行安装即可，但需要注意安装完毕后需要在 HOME 目录进行相关配置。

安装完毕后，执行 `gdb` 就可以看到：

```
$ gdb
GNU gdb (GDB) 10.2
...
(gdb) 
```

写此文时最新的 gdb 版本已经是 10.2 了，我也升级了上去。问题不大，还多了不少功能。

## 编译

我们还是使用先前的演示程序来进行调试。但由于 Go 语言的不少编译优化，因此在编译运行程序时，有以下几点需要注意：

- go build 编译时需要增加 `-gcflags=all="-N -l"` 指令来关闭内联优化，方便接下来的调试。

- 若是 MacOS，在 go build 编译时需要增加 `-ldflags='-compressdwarf=false'` 指令。
  - 若不禁止，则会出现 `No symbol table is loaded. Use the "file" command.` 的错误。
  - Go 编译默认为了减少二进制大小会默认压缩 DWARF 调试信息，但这会影响 gdb 的调试，因此需要将其关闭。
  
编译的命令是：

```
$ go build -gcflags=all="-N -l" -ldflags='-compressdwarf=false' .
```

输出结果：

```
！了鱼煎进子脑
```
  
## 尝试 gdb

GDB 有两种调试模式，分别是文本用户界面（Text User Interface，简称 tui）和默认的命令行模式：

```
// 调试界面
$ gdb -tui ./awesome-project

// 命令行模式
$ gdb ./awesome-project
```

接下来我们使用 gdb tui 的调试模式来给大家演示功能。

我们在执行命令 `gdb -tui ./awesome-project` 后，窗口会切换为如下：


![gdb tui 初始样子](https://files.mdnice.com/user/3610/2a7096f4-addd-404f-9a47-4a97cbe9d595.png)

你会发现中间提示 “No Source Available”，此时你需要继续回车两次，他就会自动加载插件支持，提示：“Loading Go Runtime support.”。

我们就可以看到具体的代码块内容，如下：

![](https://files.mdnice.com/user/3610/351571a3-b89e-42f2-941e-24e734bfae26.png)

用 MacOS 的同学需要注意，如果你在断点时发现发现了如下错误：

```
(gdb) b main.main
Breakpoint 1 at 0x10a2ea0: file /Users/eddycjy/go-application/awesomeProject/main.go, line 15.
(gdb) r
Starting program: /Users/eddycjy/go-application/awesomeProject/hello
Unable to find Mach task port for process-id 64212: (os/kern) failure (0x5).
 (please check gdb is codesigned - see taskgated(8))
```

也就是 “please check gdb is codesigned - see taskgated(8)”，则需要重新处理证书认证和授权，是 MacOS 使用上的一个问题，具体可参考：《[Codesign gdb on OSX](https://gist.github.com/hlissner/898b7dfc0a3b63824a70e15cd0180154)》。

解决后，咱们的 gdb 就算是能够正确的运行起来了！

## 常用 gdb 命令

在 gdb 中，和 dlv 一样有常用的关键字命令。当然了，gdb 的 help all 输出非常多：

```
(gdb) help all

Command class: aliases
Command class: breakpoints

awatch -- Set a watchpoint for an expression.
break, brea, bre, br, b -- Set breakpoint at specified location.
break-range -- Set a breakpoint for an address range.
catch -- Set catchpoints to catch events.
...
```

常用的关键字如下：
- b：break 的缩写，作用是打断点，例如：main.main，可带代码行数。
- r：run 的缩写，作用是运行程序到下一个断点处。
- c：continue 的缩写，作用是继续执行到下一个断点。
- s：step 的缩写，作用是单步执行，如果有所调用的方法，将会进入该方法。
- l：list 的缩写，作用是查看对应的源码。
- n：next 的缩写，作用是单步执行，不会进入所调用的方法，。
- q：quit 的缩写，作用是退出。
- info breakpoints：作用是查看所有设置的断点信息。
- info locals：作用是查看变量信息。
- info args：作用是查看函数的入参和出参的具体值。
- info goroutines：作用是查看 goroutines 的信息。
- goroutine 1 bt：作用是查看指定序号的 goroutine 调用堆栈。

## 进行调试

在调试上与 dlv 差不多，也是先执行关键字 `b` 打断点：

```
(gdb) b main.main
Breakpoint 1 at 0x10cbaa0: file /Users/eddycjy/go-application/awesomeProject/main.go, line 9.
```

也可以先执行关键字 `l` 查看对应的代码情况再进行做决定：

```
(gdb) l main.main
4		"fmt"
5	
6		"github.com/eddycjy/awesome-project/stringer"
7	)
8	
9	func main() {
10		fmt.Println(stringer.Reverse("脑子进煎鱼了！"))
11	}
```

查看对应 goroutines 正在运行的函数情况：

```
(gdb) info goroutines
  1  waiting runtime.gosched
* 13  running runtime.goexit
```

根据 pprof 等所得到的 goroutine 序号进行进一步的分析：

```
(gdb) goroutine 1 bt
#0  0x000000000040facb in runtime.gosched () at /home/user/go/src/runtime/proc.c:873
#1  0x00000000004031c9 in runtime.chanrecv (c=void, ep=void, selected=void, received=void)
 at  /home/user/go/src/runtime/chan.c:342
#2  0x0000000000403299 in runtime.chanrecv1 (t=void, c=void) at/home/user/go/src/runtime/chan.c:423
#3  0x000000000043075b in testing.RunTests (matchString...
```

注意一个细节，gdb 调试是可以看到并对 runtime 包内容的代码进行断点和分析的。

也可以和 dlv 一样执行 p 关键字输出相应的值的类型、值内容：

```
(gdb) p re
(gdb) p t
$1 = (struct testing.T *) 0xf840688b60
(gdb) p t
$1 = (struct testing.T *) 0xf840688b60
(gdb) p *t
$2 = {errors = "", failed = false, ch = 0xf8406f5690}
(gdb) p *t->ch
$3 = struct hchan<*testing.T>
```

与 dlv 大同小异。

## 总结

总体上来讲，MacOS 上使用 gdb 还是挺麻烦的，在 Linux 环境下使用 gdb 还是更方便些。

由于 **dlv 和 gdb 在大致的调试上不会差距的太远**，因此本文就没有过于展开。

若是对业务代码进行分析，更建议使用 dlv，也就是我们上一篇文章所讲的内容。**若有 runtime 库的调试需求的话，推荐使用 gdb 来作为首要调试工具**，若无这方面诉求，建议使用 dlv。

================================================
FILE: content/posts/go/generics-apis.md
================================================
---
title: "出泛型后 API 怎么办？Go 开发者要注意了"
date: 2021-12-31T12:55:14+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间社区里一下子就爆了，主要是各大媒体引用了 Go 语言之父 
Rob Pike 所提的《go: don't change the libraries in 1.18》。

![](https://files.mdnice.com/user/3610/08e47a87-cf63-4dec-b0b5-fc178a494c4c.png)

很多社交媒体都做了跟进，认为 Rob Pike 是硬性的反对 Go 泛型的 API 改造！

如果读者只看了标题，有可能会产生一些误解实际上其表达的意思和近期 Go 社区讨论的事项是有关联的，要一起综合来看。

为此，今天煎鱼就和大家一起来理一理，看看 Go 泛型 API 的改造工程，是个怎么一回事？

## 现状

马上就是 2021.11 月，连深圳都变冷了...根据 Go 语言的发布周期，Go1.18 版本的发布，那就是 2022.02 月左右。

![](https://files.mdnice.com/user/3610/f849c76d-e84d-43d6-96c5-b30df77f1dd9.png)

现在给到 Ian Lance Taylor、
Robert Griesemer 等大佬仅剩 3 个月的时间给大家讨论泛型细节，进一步完善实现，达到生产可用。

抛出 Go 泛型的实现进度不说，现在遇到了一个比较大的问题。那就是**实现泛型后 ”如何更新泛型的 API“**。

这之中包含好几个方面，分别是：既有标准库、开源库，新标准库等。不同库之间是不同的人在维护。

但这里存在一个大问题，如下图：

![](https://files.mdnice.com/user/3610/033083ef-d0ba-40f7-93d4-006e65310cf9.png)

Russ Cox 在 9 月就提出了 ”how to update APIs for generics“ 的疑惑，当时显然这一块还没有共识。在 11 月的现在，从讨论的记录来看，**怎么做还没有达成一个最终的明确共识**（初步已有，未正式答复）。

但存在一个问题，Go 社区对于泛型的迫切度，热情非常高，各种泛型化的标准库的提案都提出来了，推着设计者往前走。

## 争议

结合来看 Rob Pike，更多是：建议和提醒 Go 社区和核心开发团队，**要 ”悠着点“**，Go1.18 想支持泛型，做完成库的改造，还得代价小，毕竟细节很多。

引用其理由，核心论据是：
- 在一个版本中，做泛型、标准库等，要做的事情太多，很可能会弄错。
- 没有在 Go 中使用新类型的经验，无法为其设计提供有力的依据。
- Go1 兼容性的承诺，在任何细节上出错的代价都很高，要等待、观察和学习。

和一句谚语很接近：”**不要一口气吃胖子**“，何况没有相关的经验，都只是详细的推理、预演，需要晋升。

在 Go issues 中也有人吐槽，1.18 空有泛型的实现。其他配套的标准库等都没有，那这个 Go1.18 出来的泛型意义是？

## 后续

虽然还没有最终拍板，但是根据讨论的过程和社区赞同数（👍）来看，如下：

![](https://files.mdnice.com/user/3610/4856e2c4-7ae4-421c-812b-561ea6cf1cef.png)

后续仍然会设计、构建、测试和使用用于切片（Slice）、地图（Map）、通道（Channel）等的新库。

这些库并没有生产可用，会把他们**放在 golang/x/exp 仓库**中，可以使用，仅作为现阶段的实验性的库，没有兼容性保障。


![](https://files.mdnice.com/user/3610/47b8cae4-4ef8-42a3-af6c-686dd8acfb7a.png)


该实验库会在一两个周期内会改变、调整和发展。能够让 Go 社区的开发者们尝试一下使用，以便接受更多的意见。

再根据使用者的反馈通过经验和分析进行更新，就会把它们移到主仓库中，才达到正式生产可用的级别。

## 总结

在今天这篇文章中，我们针对 Rob Pike 为什么会要调整 Go 泛型后的标准库 API 等的提议进行了分析。

为此我们了解到 Go 核心团队对 ”how to update APIs for generics“ 的顾虑，以及现有社区的激情，综合来看，给出的逐步演进的泛型方案建议。

以此可知，Go 完整泛型（含配套库）的生产可用，可能还要经历几个 Go 版本，让不少人望穿秋水了...


================================================
FILE: content/posts/go/generics-design.md
================================================
---
title: "Go 泛型的 3 个核心设计，你学会了吗？"
date: 2022-02-05T15:52:46+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

Go1.18 的泛型是闹得沸沸扬扬，虽然之前写过很多篇针对泛型的一些设计和思考。但因为泛型的提案之前一直还没定型，所以就没有写完整介绍。

如今已经基本成型，就由煎鱼带大家一起摸透 Go 泛型。本文内容主要涉及泛型的 3 大概念，非常值得大家深入了解。

如下：
- 类型参数。
- 类型约束。
- 类型推导。

## 类型参数

类型参数，这个名词。不熟悉的小伙伴咋一看就懵逼了。

泛型代码是使用抽象的数据类型编写的，我们将其称之为类型参数。当程序运行通用代码时，类型参数就会被类型参数所取代。也就是**类型参数是泛型的抽象数据类型**。

简单的泛型例子：

```go

func Print(s []T) {
	for _, v := range s {
		fmt.Println(v)
	}
}
```

代码有一个 `Print` 函数，它打印出一个片断的每个元素，其中片断的元素类型，这里称为 T，是未知的。

这里引出了一个要做泛型语法设计的点，那就是：T 的**泛型类型参数，应该如何定义**？

在现有的设计中，分为两个部分：
- 类型参数列表：**类型参数列表将会出现在常规参数的前面**。为了区分类型参数列表和常规参数列表，类型参数列表**使用方括号**而不是小括号。
- 类型参数约束：如同常规参数有类型一样，类型参数也有元类型，被称为约束（后面会进一步介绍）。

结合完整的例子如下：

```go
// Print 可以打印任何片断的元素。
// Print 有一个类型参数 T，并有一个单一的（非类型）的 s，它是该类型参数的一个片断。
func Print[T any](s []T) {
	// do something...
}
```

在上述代码中，我们声明了一个函数 `Print`，其有一个类型参数 T，类型约束为 `any`，表示为任意的类型，作用与 `interface{}` 一样。他的入参变量 `s` 是类型 T 的切片。

函数声明完了，在函数调用时，我们需要指定类型参数的类型。如下：

```go
	Print[int]([]int{1, 2, 3})
```

在上述代码中，我们指定了传入的类型参数为 int，并传入了 `[]int{1, 2, 3}` 作为参数。

其他类型，例如 float64:

```go
	Print[float64]([]float64{0.1, 0.2, 0.3})
```

也是类似的声明方式，照着套就好了。

## 类型约束

说完类型参数，我们再说说 “约束”。在所有的类型参数中都要指定类型约束，才能叫做完整的泛型。

以下分为两个部分来具体展开讲解：
- 定义函数约束。
- 定义运算符越苏

### 为什么要有类型约束

为了**确保调用方能够满足接受方的程序诉求**，保证程序中所应用的函数、运算符等特性能够正常运行。

泛型的类型参数，类型约束，相辅相成。

### 定义函数约束

#### 问题点

我们看看 Go 官方所提供的例子：

```go
func Stringify[T any](s []T) (ret []string) {
	for _, v := range s {
		ret = append(ret, v.String()) // INVALID
	}
	return ret
}
```

该方法的实现目的是：任何类型的切片都能转换成对应的字符串切片。但程序逻辑里有一个问题，那就是他的入参 T 是 `any` 类型，是任意类型都可以传入。

其内部又调用了 `String` 方法，自然也就会报错，因为只像是 int、float64 等类型，就可能没有实现该方法。

你说要定义有效的类型约束，那像是上面的例子，在泛型中如何实现呢？

要求传入方要有内置方法，就得定义一个 `interface` 来约束他。

#### 单个类型

例子如下：

```go
type Stringer interface {
	String() string
}
```

在泛型方法中应用：

```go
func Stringify[T Stringer](s []T) (ret []string) {
	for _, v := range s {
		ret = append(ret, v.String())
	}
	return ret
}
```

再将 `Stringer` 类型放到原有的 `any` 类型处，就可以实现程序所需的诉求了。

#### 多个类型

如果是多个类型约束。例子如下：

```go
type Stringer interface {
	String() string
}

type Plusser interface {
	Plus(string) string
}

func ConcatTo[S Stringer, P Plusser](s []S, p []P) []string {
	r := make([]string, len(s))
	for i, v := range s {
		r[i] = p[i].Plus(v.String())
	}
	return r
}
```

与常规的入参、出参类型声明一样的规则。

### 定义运算符约束

完成了函数约束的定义后，剩下一个要啃的大骨头就是 “运算符” 的约束了。

#### 问题点

我们看看 Go 官方的例子：

```go
func Smallest[T any](s []T) T {
	r := s[0] // panic if slice is empty
	for _, v := range s[1:] {
		if v < r { // INVALID
			r = v
		}
	}
	return r
}
```

经过上面的函数例子，我们很快能意识到这个程序根本无法运行成功。

其入参是 `any` 类型，程序内部是按 slice 类型来获取值，且在内部又进行运算符比较，那如果真是 slice，内部就可能每个值类型都不一样。

如果一个是 slice，一个是 int 类型，又如何进行运算符的值对比？

#### 近似元素

可能有的同学想到了重载运算符，但...想太多了，Go 语言没有支持的计划。为此做了一个新的设计，那就是允许限制类型参数的类型范围。

语法如下：

```go
InterfaceType  = "interface" "{" {(MethodSpec | InterfaceTypeName | ConstraintElem) ";" } "}" .
ConstraintElem = ConstraintTerm { "|" ConstraintTerm } .
ConstraintTerm = ["~"] Type .
```

例子如下：

```go
type AnyInt interface{ ~int }
```

上述声明的类型集是 `~int`，也就是所有类型为 int 的类型（如：int、int8、int16、int32、int64）都能够满足这个类型约束的条件。

包括底层类型是 int8 类型的，例如：

```go
type AnyInt8 int8
```

也就是在该匹配范围内的。

#### 联合元素

如果希望进一步缩小限定类型，可以结合分隔符来使用，用法为：

```go
type AnyInt interface{
 ~int8 | ~int64
}
```

就可以将类型集限定在 int8 和 int64 之中。

#### 实现运算符约束

基于新的语法，结合新的概念联合和近似元素，可以把程序改造一下，实现在泛型中的运算符的匹配。

类型约束的声明，如下：

```go
type Ordered interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
		~float32 | ~float64 |
		~string
}
```

应用的程序如下：

```go
func Smallest[T Ordered](s []T) T {
	r := s[0] // panics if slice is empty
	for _, v := range s[1:] {
		if v < r {
			r = v
		}
	}
	return r
}
```

确保了值均为基础数据类型后，程序就可以正常运行了。

## 类型推导

程序员写代码，一定程度的偷懒是必然的。

在一定的场景下，可以通过类型推导来避免明确地写出一些或所有的类型参数，编译器会进行自动识别。

建议复杂函数和参数能明确是最好的，否则读代码的同学会比较麻烦，可读性和可维护性的保证也是工作中重要的一点。

### 参数推导

函数例子。如下：

```go
func Map[F, T any](s []F, f func(F) T) []T { ... }
```

公共代码片段。如下：

```go
var s []int
f := func(i int) int64 { return int64(i) }
var r []int64
```
明确指定两个类型参数。如下：

```go
r = Map[int, int64](s, f)
```

只指定第一个类型参数，变量 f 被推断出来。如下：

```go
r = Map[int](s, f)
```

不指定任何类型参数，让两者都被推断出来。如下：

```go
r = Map(s, f)
```

### 约束推导

神奇的在于，类型推导不仅限与此，连约束都可以推导。

函数例子，如下：

```go
func Double[E constraints.Number](s []E) []E {
	r := make([]E, len(s))
	for i, v := range s {
		r[i] = v + v
	}
	return r
}
```

基于此的推导案例，如下：

```go
type MySlice []int

var V1 = Double(MySlice{1})
```

MySlice 是一个 int 的切片类型别名。变量 V1 的类型编译器推导后 []int 类型，并不是 MySlice。

原因在于编译器在比较两者的类型时，会将 MySlice 类型识别为 []int，也就是 int 类型。

要实现 “正确” 的推导，需要如下定义：

```go
type SC[E any] interface {
	[]E 
}

func DoubleDefined[S SC[E], E constraints.Number](s S) S {
	r := make(S, len(s))
	for i, v := range s {
		r[i] = v + v
	}
	return r
}
```

基于此的推导案例。如下：

```go
var V2 = DoubleDefined[MySlice, int](MySlice{1})
```

只要定义显式类型参数，就可以获得正确的类型，变量 V2 的类型会是 MySlice。

那如果不声明约束呢？如下：

```go
var V3 = DoubleDefined(MySlice{1})
```

编译器通过函数参数进行推导，也可以明确变量 V3 类型是 MySlice。

## 总结

今天我们在文章中给大家介绍了泛型的三个重要概念，分别是：
- 类型参数：泛型的抽象数据类型。
- 类型约束：确保调用方能够满足接受方的程序诉求。
- 类型推导：避免明确地写出一些或所有的类型参数。

在内容中也涉及到了联合元素、近似元素、函数约束、运算符约束等新概念。本质上都是基于三个大概念延伸出来的新解决方法，一环扣一环。

你学会 Go 泛型了吗，设计的如何，欢迎一起和煎鱼讨论：）

## 参考
- [Type Parameters Proposal](https://go.googlesource.com/proposal/+/refs/heads/master/design/43651-type-parameters.md)
- [Summary of Go Generics Discussions](https://docs.google.com/document/d/1vrAy9gMpMoS3uaVphB32uVXX4pi-HnNjkMEgyAHX4N4/)

================================================
FILE: content/posts/go/generics-proposal.md
================================================
---
title: "快报：正式提案将泛型特性加入 Go 语言"
date: 2021-01-13T21:11:44+08:00
toc: true
images:
tags: 
  - 泛型
---

经历九九八十一难，多年的不断探讨和 Go 语言爱好者们在社区中的强烈关注，且 Go 官方在 2020 年不断放出消息。

![image](https://image.eddycjy.com/1d0e5a264c65e37659f142bc2ee55805.jpg)

总算在 2021 年 1 月 12 日。官方正式提出将泛型特性加入 Go 语言的 proposal 了，且最新的草案设计已经更新。


基本语法如下：

```
func Print[T any](s []T) {
	// same as above
}
```

其大体的概述如下：

- 函数可以具有使用方括号的其他类型参数列表，但其他情况下看起来像普通的参数列表：`func F[T any](p T) { ... }`。
- 类型也可以具有类型参数列表：`type MySlice[T any] []T`。
- 每个类型参数都有一个类型约束，就像每个普通参数都有一个类型：`func F[T Constraint](p T) { ... }`。
- 类型约束是接口类型。
- 新的预声明名称 `any` 是允许任何类型的类型约束。
- 用作类型约束的接口类型可以具有预先声明的类型的列表。只有与那些类型之一匹配的类型参数才能满足约束条件。
- 泛型函数只能使用其类型约束所允许的操作。
- 使用泛型函数或类型需要传递类型实参。
- 在通常情况下，类型推断允许省略函数调用的类型参数。

根据官方博客的消息，如果该提案被正式接受。那么将会在 2021 年底之前完成一个基本可用的泛型特性使用，又或是会作为 Go1.18beta 的一部分。

这是 Go 泛型特性的又一步前进。若大家有兴趣进一步了解或想提出意见，可查看下述传送门：

- A Proposal for Adding Generics to Go：https://blog.golang.org/generics-proposal。
- proposal: spec: add generic programming using type parameters：https://github.com/golang/go/issues/43651。

今年年底或 Go1.18beta 到底能不能看到泛型的正式完整可用版本呢，值得期待。

================================================
FILE: content/posts/go/gin/2018-02-10-install.md
================================================
---

title:      "「连载一」Go 介绍与环境安装"
date:       2018-02-10 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 本文目标

- 学会安装 Go。
- 知道什么是 Go。
- 知道什么是 Go modules。
- 了解 Go modules 的小历史。
- 学会简单的使用 Go modules。
- 了解 Gin，并简单跑起一个 Demo。

## 准备环节

### 安装 Go

#### Centos

首先，根据对应的操作系统选择安装包 [下载](https://studygolang.com/dl)，在这里我使用的是 Centos 64 位系统，如下：

```sh
$ wget https://studygolang.com/dl/golang/go1.13.1.linux-amd64.tar.gz

$ tar -zxvf go1.13.1.linux-amd64.tar.gz

$ mv go/ /usr/local/
```

配置 /etc/profile

```sh
vi /etc/profile
```

添加环境变量 GOROOT 和将 GOBIN 添加到 PATH 中

```sh
export GOROOT=/usr/local/go
export PATH=$PATH:$GOROOT/bin
```

配置完毕后，执行命令令其生效

```sh
source /etc/profile
```

在控制台输入`go version`，若输出版本号则**安装成功**，如下：

```
$ go version
go version go1.13.1 linux/amd64
```

#### MacOS

在 MacOS 上安装 Go 最方便的办法就是使用 brew，安装如下：

```
$ brew install go
```

升级命令如下：

```
$ brew upgrade go
```

注：升级命令你不需要执行，但我想未来你有一天会用到的。

同样在控制台输入`go version`，若输出版本号则**安装成功**。

### 了解 Go

#### 是什么

> Go is an open source programming language that makes it easy to build simple, reliable, and efficient software.

上述为官方说明，如果简单来讲，大致为如下几点：

- Go 是编程语言。
- 谷歌爸爸撑腰。
- 语言级高并发。
- 上手快，入门简单。
- 简洁，很有特色。
- 国内使用人群逐年增多。

#### 谁在用

![image](https://image.eddycjy.com/6d278b22a4c0bf29c6b89ece99cd6c88.jpg)

#### 有什么

那么大家会有些疑问，纠结 `Go` 本身有什么东西，我们刚刚设置的环境变量又有什么用呢，甚至作为一名老粉，你会纠结 GOPATH 去哪里了，我们一起接着往下看。

##### 目录结构

首先，我们在解压的时候会得到一个名为 `go` 的文件夹，其中包括了所有 `Go` 语言相关的一些文件，如下：

```
$ tree -L 1 go
go
├── api
├── bin
├── doc
├── lib
├── misc
├── pkg
├── src
├── test
└── ...
```

在这之中包含了很多文件夹和文件，我们来简单说明其中主要文件夹的作用：

- api：用于存放依照 `Go` 版本顺序的 API 增量列表文件。这里所说的 API 包含公开的变量、常量、函数等。这些 API 增量列表文件用于 `Go` 语言 API 检查
- bin：用于存放主要的标准命令文件（可执行文件），包含`go`、`godoc`、`gofmt`
- blog：用于存放官方博客中的所有文章
- doc：用于存放标准库的 HTML 格式的程序文档。我们可以通过`godoc`命令启动一个 Web 程序展示这些文档
- lib：用于存放一些特殊的库文件
- misc：用于存放一些辅助类的说明和工具
- pkg：用于存放安装`Go`标准库后的所有归档文件（以`.a`结尾的文件）。注意，你会发现其中有名称为`linux_amd64`的文件夹，我们称为平台相关目录。这类文件夹的名称由对应的操作系统和计算架构的名称组合而成。通过`go install`命令，`Go`程序会被编译成平台相关的归档文件存放到其中
- src：用于存放 `Go`自身、`Go` 标准工具以及标准库的所有源码文件
- test：存放用来测试和验证`Go`本身的所有相关文件

##### 环境变量

你可能会疑惑刚刚设置的环境变量是什么，如下：

- GOROOT：`Go`的根目录。
- PATH 下增加 `$GOROOT/bin`：`Go`的 `bin`下会存放可执行文件，我们把他加入 `$PATH` 后，未来拉下来并编译后的二进制文件就可以直接在命令行使用。

那在什么东西都不下载的情况下，`$GOBIN` 下面有什么呢，如下：

```
bin/ $ls
go  gofmt
```

- go：`Go` 二进制本身。
- gofmt：代码格式化工具。

因此我们刚刚把 `$GOBIN` 加入到 `$PATH` 后，你执行 `go version` 命令后就可以查看到对应的输出结果。

注：MacOS 用 brew 安装的话就不需要。

#### 放在哪

你现在知道 Go 是什么了，也知道 Go 的源码摆在哪了，你肯定会想，那我应用代码放哪呢，答案是在 **Go1.11+ 和开启 Go Modules 的情况下摆哪都行**。

### 了解 Go Modules

#### 了解历史

在过去，Go 的依赖包管理在工具上混乱且不统一，有 dep，有 glide，有 govendor...甚至还有因为外网的问题，频频导致拉不下来包，很多人苦不堪言，盼着官方给出一个大一统做出表率。

而在 Go modules 正式出来之前还有一个叫 dep 的项目，我们在上面有提到，它是 Go 的一个官方实验性项目，目的也是为了解决 Go 在依赖管理方面的问题，当时社区里面几乎所有的人都认为 dep 肯定就是未来 Go 官方的依赖管理解决方案了。

但是万万没想到，半路杀出个程咬金，Russ Cox 义无反顾地推出了 Go modules，这瞬间导致一石激起千层浪，让社区炸了锅。大家一致认为 Go team 实在是太霸道、太独裁了，连个招呼都不打一声。我记得当时有很多人在网上跟 Russ Cox 口水战，各种依赖管理解决方案的专家都冒出来发表意见，讨论范围甚至一度超出了 Go 语言的圈子触及到了其他语言的领域。

当然，最后，推成功了，Go modules 已经进入官方工具链中，与 Go 深深结合，以前常说的 GOPATH 终将会失去它原有的作用，而且它还提供了 GOPROXY 间接解决了国内访问外网的问题。

#### 了解 Russ Cox

在上文中提到的 Russ Cox 是谁呢，他是 Go 这个项目目前代码提交量最多的人，甚至是第二名的两倍还要多（从 2019 年 09 月 30 日前来看）。

Russ Cox 还是 Go 现在的掌舵人（大家应该知道之前 Go 的掌舵人是 Rob Pike，但是听说由于他本人不喜欢特朗普执政所以离开了美国，然后他岁数也挺大的了，所以也正在逐渐交权，不过现在还是在参与 Go 的发展）。

Russ Cox 的个人能力相当强，看问题的角度也很独特，这也就是为什么他刚一提出 Go modules 的概念就能引起那么大范围的响应。虽然是被强推的，但事实也证明当下的 Go modules 表现得确实很优秀，所以这表明一定程度上的 “独裁” 还是可以接受的，至少可以保证一个项目能更加专一地朝着一个方向发展。

#### 初始化行为

在前面我们已经了解到 Go 依赖包管理的历史情况，接下来我们将正式的进入使用，首先你需要有一个你喜欢的目录，例如：`$ mkdir ~/go-application && cd ~/go-application`，然后执行如下命令：

```
$ mkdir go-gin-example && cd go-gin-example

$ go env -w GO111MODULE=on

$ go env -w GOPROXY=https://goproxy.cn,direct

$ go mod init github.com/EDDYCJY/go-gin-example
go: creating new go.mod: module github.com/EDDYCJY/go-gin-example

$ ls
go.mod
```

- `mkdir xxx && cd xxx`：创建并切换到项目目录里去。
- `go env -w GO111MODULE=on`：打开 Go modules 开关（目前在 Go1.13 中默认值为 `auto`）。
- `go env -w GOPROXY=...`：设置 GOPROXY 代理，这里主要涉及到两个值，第一个是 `https://goproxy.cn`，它是由七牛云背书的一个强大稳定的 Go 模块代理，可以有效地解决你的外网问题；第二个是 `direct`，它是一个特殊的 fallback 选项，它的作用是用于指示 Go 在拉取模块时遇到错误会回源到模块版本的源地址去抓取（比如 GitHub 等）。
- `go mod init [MODULE_PATH]`：初始化 Go modules，它将会生成 go.mod 文件，需要注意的是 `MODULE_PATH` 填写的是模块引入路径，你可以根据自己的情况修改路径。

在执行了上述步骤后，初始化工作已完成，我们打开 `go.mod` 文件看看，如下：

```
module github.com/EDDYCJY/go-gin-example

go 1.13
```

默认的 `go.mod` 文件里主要是两块内容，一个是当前的模块路径和预期的 Go 语言版本。

#### 基础使用

- 用 `go get` 拉取新的依赖
  - 拉取最新的版本(优先择取 tag)：`go get golang.org/x/text@latest`
  - 拉取 `master` 分支的最新 commit：`go get golang.org/x/text@master`
  - 拉取 tag 为 v0.3.2 的 commit：`go get golang.org/x/text@v0.3.2`
  - 拉取 hash 为 342b231 的 commit，最终会被转换为 v0.3.2：`go get golang.org/x/text@342b2e`
  - 用 `go get -u` 更新现有的依赖
  - 用 `go mod download` 下载 go.mod 文件中指明的所有依赖
  - 用 `go mod tidy` 整理现有的依赖
  - 用 `go mod graph` 查看现有的依赖结构
  - 用 `go mod init` 生成 go.mod 文件 (Go 1.13 中唯一一个可以生成 go.mod 文件的子命令)
- 用 `go mod edit` 编辑 go.mod 文件
- 用 `go mod vendor` 导出现有的所有依赖 (事实上 Go modules 正在淡化 Vendor 的概念)
- 用 `go mod verify` 校验一个模块是否被篡改过

这一小节主要是针对 Go modules 的基础使用讲解，还没具体的使用，是希望你能够留个印象，因为在后面章节会不断夹杂 Go modules 的知识点。

注：建议阅读官方文档 [wiki/Modules](https://github.com/golang/go/wiki/Modules)。

## 开始 Gin 之旅

### 是什么

> Gin is a HTTP web framework written in Go (Golang). It features a Martini-like API with much better performance -- up to 40 times faster. If you need smashing performance, get yourself some Gin.

Gin 是用 Go 开发的一个微框架，类似 Martinier 的 API，重点是小巧、易用、性能好很多，也因为 [httprouter](https://github.com/julienschmidt/httprouter) 的性能提高了 40 倍。

### 安装

我们回到刚刚创建的 `go-gin-example` 目录下，在命令行下执行如下命令：

```sh
$ go get -u github.com/gin-gonic/gin
go: downloading golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223
go: extracting golang.org/x/sys v0.0.0-20190222072716-a9d3bda3a223
go: finding github.com/gin-contrib/sse v0.1.0
go: finding github.com/ugorji/go v1.1.7
go: finding gopkg.in/yaml.v2 v2.2.3
go: finding golang.org/x/sys latest
go: finding github.com/mattn/go-isatty v0.0.9
go: finding github.com/modern-go/concurrent latest
...
```

#### go.sum

这时候你再检查一下该目录下，会发现多个了个 `go.sum` 文件，如下：

```
github.com/davecgh/go-spew v1.1.0/go.mod h1:J7Y8YcW...
github.com/davecgh/go-spew v1.1.1/go.mod h1:J7Y8YcW...
github.com/gin-contrib/sse v0.0.0-20190301062529-5545eab6dad3 h1:t8FVkw33L+wilf2QiWkw0UV77qRpcH/JHPKGpKa2E8g=
github.com/gin-contrib/sse v0.0.0-20190301062529-5545eab6dad3/go.mod h1:VJ0WA2...
github.com/gin-contrib/sse v0.1.0 h1:Y/yl/+YNO...
...
```

`go.sum` 文件详细罗列了当前项目直接或间接依赖的所有模块版本，并写明了那些模块版本的 SHA-256 哈希值以备 Go 在今后的操作中保证项目所依赖的那些模块版本不会被篡改。

#### go.mod

既然我们下载了依赖包，`go.mod` 文件会不会有所改变呢，我们再去看看，如下：

```
module github.com/EDDYCJY/go-gin-example

go 1.13

require (
        github.com/gin-contrib/sse v0.1.0 // indirect
        github.com/gin-gonic/gin v1.4.0 // indirect
        github.com/golang/protobuf v1.3.2 // indirect
        github.com/json-iterator/go v1.1.7 // indirect
        github.com/mattn/go-isatty v0.0.9 // indirect
        github.com/ugorji/go v1.1.7 // indirect
        golang.org/x/sys v0.0.0-20190927073244-c990c680b611 // indirect
        gopkg.in/yaml.v2 v2.2.3 // indirect
)
```

确确实实发生了改变，那多出来的东西又是什么呢，`go.mod` 文件又保存了什么信息呢，实际上 `go.mod` 文件是启用了 Go modules 的项目所必须的最重要的文件，因为它描述了当前项目（也就是当前模块）的元信息，每一行都以一个动词开头，目前有以下 5 个动词:

- module：用于定义当前项目的模块路径。
- go：用于设置预期的 Go 版本。
- require：用于设置一个特定的模块版本。
- exclude：用于从使用中排除一个特定的模块版本。
- replace：用于将一个模块版本替换为另外一个模块版本。

你可能还会疑惑 `indirect` 是什么东西，`indirect` 的意思是传递依赖，也就是非直接依赖。

### 测试

编写一个`test.go`文件

```go
package main

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

func main() {
  r := gin.Default()
  r.GET("/ping", func(c *gin.Context) {
    c.JSON(200, gin.H{
      "message": "pong",
    })
  })
  r.Run() // listen and serve on 0.0.0.0:8080
}
```

执行`test.go`

```sh
$ go run test.go
...
[GIN-debug] GET    /ping                     --> main.main.func1 (3 handlers)
[GIN-debug] Environment variable PORT is undefined. Using port :8080 by default
[GIN-debug] Listening and serving HTTP on :8080
```

访问 `$HOST:8080/ping`，若返回`{"message":"pong"}`则正确

```sh
curl 127.0.0.1:8080/ping
```

至此，我们的环境安装和初步运行都基本完成了。

## 再想一想

刚刚在执行了命令 `$ go get -u github.com/gin-gonic/gin` 后，我们查看了 `go.mod` 文件，如下：

```
...
require (
        github.com/gin-contrib/sse v0.1.0 // indirect
        github.com/gin-gonic/gin v1.4.0 // indirect
        ...
)
```

你会发现 `go.mod` 里的 `github.com/gin-gonic/gin` 是 `indirect` 模式，这显然不对啊，因为我们的应用程序已经实际的编写了 gin server 代码了，我就想把它调对，怎么办呢，在应用根目录下执行如下命令：

```
$ go mod tidy
```

该命令主要的作用是整理现有的依赖，非常的常用，执行后 `go.mod` 文件内容为：

```
...
require (
        github.com/gin-contrib/sse v0.1.0 // indirect
        github.com/gin-gonic/gin v1.4.0
        ...
)
```

可以看到 `github.com/gin-gonic/gin` 已经变成了直接依赖，调整完毕。

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

### 相关文档

- [Gin](https://github.com/gin-gonic/gin)
- [Gin Web Framework](https://gin-gonic.github.io/gin/)
- [干货满满的 Go Modules 和 goproxy.cn](https://book.eddycjy.com/golang/talk/goproxy-cn.html)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-02-11-api-01.md
================================================
---

title:      "「连载二」Gin搭建Blog API's （一）"
date:       2018-02-11 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 思考

首先，在一个初始项目开始前，大家都要思考一下

- 程序的文本配置写在代码中，好吗？

- API 的错误码硬编码在程序中，合适吗？

- db 句柄谁都去`Open`，没有统一管理，好吗？

- 获取分页等公共参数，谁都自己写一套逻辑，好吗？

显然在较正规的项目中，这些问题的答案都是**不可以**，为了解决这些问题，我们挑选一款读写配置文件的库，目前比较火的有 [viper](https://github.com/spf13/viper)，有兴趣你未来可以简单了解一下，没兴趣的话等以后接触到再说。

但是本系列选用 [go-ini/ini](https://github.com/go-ini/ini) ，它的 [中文文档](https://ini.unknwon.io/)。大家是必须需要要简单阅读它的文档，再接着完成后面的内容。

## 本文目标

- 编写一个简单的 API 错误码包。
- 完成一个 Demo 示例。
- 讲解 Demo 所涉及的知识点。

## 介绍和初始化项目

### 初始化项目目录

在前一章节中，我们初始化了一个 `go-gin-example` 项目，接下来我们需要继续新增如下目录结构：

```
go-gin-example/
├── conf
├── middleware
├── models
├── pkg
├── routers
└── runtime
```

- conf：用于存储配置文件
- middleware：应用中间件
- models：应用数据库模型
- pkg：第三方包
- routers 路由逻辑处理
- runtime：应用运行时数据

### 添加 Go Modules Replace

打开 `go.mod` 文件，新增 `replace` 配置项，如下：

```
module github.com/EDDYCJY/go-gin-example

go 1.13

require (...)

replace (
		github.com/EDDYCJY/go-gin-example/pkg/setting => ~/go-application/go-gin-example/pkg/setting
		github.com/EDDYCJY/go-gin-example/conf    	  => ~/go-application/go-gin-example/pkg/conf
		github.com/EDDYCJY/go-gin-example/middleware  => ~/go-application/go-gin-example/middleware
		github.com/EDDYCJY/go-gin-example/models 	  => ~/go-application/go-gin-example/models
		github.com/EDDYCJY/go-gin-example/routers 	  => ~/go-application/go-gin-example/routers
)
```

可能你会不理解为什么要特意跑来加 `replace` 配置项，首先你要看到我们使用的是完整的外部模块引用路径（`github.com/EDDYCJY/go-gin-example/xxx`），而这个模块还没推送到远程，是没有办法下载下来的，因此需要用 `replace` 将其指定读取本地的模块路径，这样子就可以解决本地模块读取的问题。

**注：后续每新增一个本地应用目录，你都需要主动去 go.mod 文件里新增一条 replace（我不会提醒你），如果你漏了，那么编译时会出现报错，找不到那个模块。**

### 初始项目数据库

新建 `blog` 数据库，编码为`utf8_general_ci`，在 `blog` 数据库下，新建以下表

**1、 标签表**

```sql
CREATE TABLE `blog_tag` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `name` varchar(100) DEFAULT '' COMMENT '标签名称',
  `created_on` int(10) unsigned DEFAULT '0' COMMENT '创建时间',
  `created_by` varchar(100) DEFAULT '' COMMENT '创建人',
  `modified_on` int(10) unsigned DEFAULT '0' COMMENT '修改时间',
  `modified_by` varchar(100) DEFAULT '' COMMENT '修改人',
  `deleted_on` int(10) unsigned DEFAULT '0',
  `state` tinyint(3) unsigned DEFAULT '1' COMMENT '状态 0为禁用、1为启用',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='文章标签管理';
```

**2、 文章表**

```sql
CREATE TABLE `blog_article` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `tag_id` int(10) unsigned DEFAULT '0' COMMENT '标签ID',
  `title` varchar(100) DEFAULT '' COMMENT '文章标题',
  `desc` varchar(255) DEFAULT '' COMMENT '简述',
  `content` text,
  `created_on` int(11) DEFAULT NULL,
  `created_by` varchar(100) DEFAULT '' COMMENT '创建人',
  `modified_on` int(10) unsigned DEFAULT '0' COMMENT '修改时间',
  `modified_by` varchar(255) DEFAULT '' COMMENT '修改人',
  `deleted_on` int(10) unsigned DEFAULT '0',
  `state` tinyint(3) unsigned DEFAULT '1' COMMENT '状态 0为禁用1为启用',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8 COMMENT='文章管理';
```

**3、 认证表**

```sql
CREATE TABLE `blog_auth` (
  `id` int(10) unsigned NOT NULL AUTO_INCREMENT,
  `username` varchar(50) DEFAULT '' COMMENT '账号',
  `password` varchar(50) DEFAULT '' COMMENT '密码',
  PRIMARY KEY (`id`)
) ENGINE=InnoDB DEFAULT CHARSET=utf8;

INSERT INTO `blog`.`blog_auth` (`id`, `username`, `password`) VALUES (null, 'test', 'test123456');

```

## 编写项目配置包

在 `go-gin-example` 应用目录下，拉取 `go-ini/ini` 的依赖包，如下：

```
$ go get -u github.com/go-ini/ini
go: finding github.com/go-ini/ini v1.48.0
go: downloading github.com/go-ini/ini v1.48.0
go: extracting github.com/go-ini/ini v1.48.0
```

接下来我们需要编写基础的应用配置文件，在 `go-gin-example` 的`conf`目录下新建`app.ini`文件，写入内容：

```ini
#debug or release
RUN_MODE = debug

[app]
PAGE_SIZE = 10
JWT_SECRET = 23347$040412

[server]
HTTP_PORT = 8000
READ_TIMEOUT = 60
WRITE_TIMEOUT = 60

[database]
TYPE = mysql
USER = 数据库账号
PASSWORD = 数据库密码
#127.0.0.1:3306
HOST = 数据库IP:数据库端口号
NAME = blog
TABLE_PREFIX = blog_
```

建立调用配置的`setting`模块，在`go-gin-example`的`pkg`目录下新建`setting`目录（注意新增 replace 配置），新建 `setting.go` 文件，写入内容：

```go
package setting

import (
	"log"
	"time"

	"github.com/go-ini/ini"
)

var (
	Cfg *ini.File

	RunMode string

	HTTPPort int
	ReadTimeout time.Duration
	WriteTimeout time.Duration

	PageSize int
	JwtSecret string
)

func init() {
	var err error
	Cfg, err = ini.Load("conf/app.ini")
	if err != nil {
		log.Fatalf("Fail to parse 'conf/app.ini': %v", err)
	}

	LoadBase()
	LoadServer()
	LoadApp()
}

func LoadBase() {
	RunMode = Cfg.Section("").Key("RUN_MODE").MustString("debug")
}

func LoadServer() {
	sec, err := Cfg.GetSection("server")
	if err != nil {
		log.Fatalf("Fail to get section 'server': %v", err)
	}

	HTTPPort = sec.Key("HTTP_PORT").MustInt(8000)
	ReadTimeout = time.Duration(sec.Key("READ_TIMEOUT").MustInt(60)) * time.Second
	WriteTimeout =  time.Duration(sec.Key("WRITE_TIMEOUT").MustInt(60)) * time.Second
}

func LoadApp() {
	sec, err := Cfg.GetSection("app")
	if err != nil {
		log.Fatalf("Fail to get section 'app': %v", err)
	}

	JwtSecret = sec.Key("JWT_SECRET").MustString("!@)*#)!@U#@*!@!)")
	PageSize = sec.Key("PAGE_SIZE").MustInt(10)
}
```

当前的目录结构：

```
go-gin-example
├── conf
│   └── app.ini
├── go.mod
├── go.sum
├── middleware
├── models
├── pkg
│   └── setting.go
├── routers
└── runtime
```

## 编写 API 错误码包

建立错误码的`e`模块，在`go-gin-example`的`pkg`目录下新建`e`目录（注意新增 replace 配置），新建`code.go`和`msg.go`文件，写入内容：

**1、 code.go：**

```go
package e

const (
	SUCCESS = 200
	ERROR = 500
	INVALID_PARAMS = 400

	ERROR_EXIST_TAG = 10001
	ERROR_NOT_EXIST_TAG = 10002
	ERROR_NOT_EXIST_ARTICLE = 10003

	ERROR_AUTH_CHECK_TOKEN_FAIL = 20001
	ERROR_AUTH_CHECK_TOKEN_TIMEOUT = 20002
	ERROR_AUTH_TOKEN = 20003
	ERROR_AUTH = 20004
)
```

**2、 msg.go：**

```go
package e

var MsgFlags = map[int]string {
	SUCCESS : "ok",
	ERROR : "fail",
	INVALID_PARAMS : "请求参数错误",
	ERROR_EXIST_TAG : "已存在该标签名称",
	ERROR_NOT_EXIST_TAG : "该标签不存在",
	ERROR_NOT_EXIST_ARTICLE : "该文章不存在",
	ERROR_AUTH_CHECK_TOKEN_FAIL : "Token鉴权失败",
	ERROR_AUTH_CHECK_TOKEN_TIMEOUT : "Token已超时",
	ERROR_AUTH_TOKEN : "Token生成失败",
	ERROR_AUTH : "Token错误",
}

func GetMsg(code int) string {
	msg, ok := MsgFlags[code]
	if ok {
		return msg
	}

	return MsgFlags[ERROR]
}
```

## 编写工具包

在`go-gin-example`的`pkg`目录下新建`util`目录（注意新增 replace 配置），并拉取`com`的依赖包，如下：

```
$ go get -u github.com/unknwon/com
```

### 编写分页页码的获取方法

在`util`目录下新建`pagination.go`，写入内容：

```go
package util

import (
	"github.com/gin-gonic/gin"
	"github.com/unknwon/com"

	"github.com/EDDYCJY/go-gin-example/pkg/setting"
)

func GetPage(c *gin.Context) int {
	result := 0
	page, _ := com.StrTo(c.Query("page")).Int()
    if page > 0 {
        result = (page - 1) * setting.PageSize
    }

    return result
}
```

## 编写 models init

拉取`gorm`的依赖包，如下：

```
$ go get -u github.com/jinzhu/gorm
```

拉取`mysql`驱动的依赖包，如下：

```
$ go get -u github.com/go-sql-driver/mysql
```

完成后，在`go-gin-example`的`models`目录下新建`models.go`，用于`models`的初始化使用

```go
package models

import (
	"log"
	"fmt"

	"github.com/jinzhu/gorm"
	_ "github.com/jinzhu/gorm/dialects/mysql"

	"github.com/EDDYCJY/go-gin-example/pkg/setting"
)

var db *gorm.DB

type Model struct {
	ID int `gorm:"primary_key" json:"id"`
	CreatedOn int `json:"created_on"`
	ModifiedOn int `json:"modified_on"`
}

func init() {
	var (
		err error
		dbType, dbName, user, password, host, tablePrefix string
	)

	sec, err := setting.Cfg.GetSection("database")
	if err != nil {
		log.Fatal(2, "Fail to get section 'database': %v", err)
	}

	dbType = sec.Key("TYPE").String()
	dbName = sec.Key("NAME").String()
	user = sec.Key("USER").String()
	password = sec.Key("PASSWORD").String()
	host = sec.Key("HOST").String()
	tablePrefix = sec.Key("TABLE_PREFIX").String()

	db, err = gorm.Open(dbType, fmt.Sprintf("%s:%s@tcp(%s)/%s?charset=utf8&parseTime=True&loc=Local",
		user,
		password,
		host,
		dbName))

	if err != nil {
		log.Println(err)
	}

	gorm.DefaultTableNameHandler = func (db *gorm.DB, defaultTableName string) string  {
	    return tablePrefix + defaultTableName;
	}

	db.SingularTable(true)
	db.LogMode(true)
	db.DB().SetMaxIdleConns(10)
	db.DB().SetMaxOpenConns(100)
}

func CloseDB() {
	defer db.Close()
}
```

## 编写项目启动、路由文件

最基础的准备工作完成啦，让我们开始编写 Demo 吧！

### 编写 Demo

在`go-gin-example`下建立`main.go`作为启动文件（也就是`main`包），我们先写个**Demo**，帮助大家理解，写入文件内容：

```go
package main

import (
    "fmt"
    "net/http"

    "github.com/gin-gonic/gin"

    "github.com/EDDYCJY/go-gin-example/pkg/setting"
)

func main() {
    router := gin.Default()
    router.GET("/test", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "test",
		})
	})

	s := &http.Server{
		Addr:           fmt.Sprintf(":%d", setting.HTTPPort),
		Handler:        router,
		ReadTimeout:    setting.ReadTimeout,
		WriteTimeout:   setting.WriteTimeout,
		MaxHeaderBytes: 1 << 20,
	}

	s.ListenAndServe()
}
```

执行`go run main.go`，查看命令行是否显示

```
[GIN-debug] [WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.

[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /test                     --> main.main.func1 (3 handlers)
```

在本机执行`curl 127.0.0.1:8000/test`，检查是否返回`{"message":"test"}`。

### 知识点

**那么，我们来延伸一下 Demo 所涉及的知识点！**

##### 标准库

- [fmt](https://golang.org/pkg/fmt/)：实现了类似 C 语言 printf 和 scanf 的格式化 I/O。格式化动作（'verb'）源自 C 语言但更简单
- [net/http](https://golang.org/pkg/net/http/)：提供了 HTTP 客户端和服务端的实现

##### **Gin**

- [gin.Default()](https://gowalker.org/github.com/gin-gonic/gin#Default)：返回 Gin 的`type Engine struct{...}`，里面包含`RouterGroup`，相当于创建一个路由`Handlers`，可以后期绑定各类的路由规则和函数、中间件等
- [router.GET(...){...}](https://gowalker.org/github.com/gin-gonic/gin#IRoutes)：创建不同的 HTTP 方法绑定到`Handlers`中，也支持 POST、PUT、DELETE、PATCH、OPTIONS、HEAD 等常用的 Restful 方法
- [gin.H{...}](https://gowalker.org/github.com/gin-gonic/gin#H)：就是一个`map[string]interface{}`
- [gin.Context](https://gowalker.org/github.com/gin-gonic/gin#Context)：`Context`是`gin`中的上下文，它允许我们在中间件之间传递变量、管理流、验证 JSON 请求、响应 JSON 请求等，在`gin`中包含大量`Context`的方法，例如我们常用的`DefaultQuery`、`Query`、`DefaultPostForm`、`PostForm`等等

##### &http.Server 和 ListenAndServe？

1、http.Server：

```go
type Server struct {
    Addr    string
    Handler Handler
    TLSConfig *tls.Config
    ReadTimeout time.Duration
    ReadHeaderTimeout time.Duration
    WriteTimeout time.Duration
    IdleTimeout time.Duration
    MaxHeaderBytes int
    ConnState func(net.Conn, ConnState)
    ErrorLog *log.Logger
}
```

- Addr：监听的 TCP 地址，格式为`:8000`
- Handler：http 句柄，实质为`ServeHTTP`，用于处理程序响应 HTTP 请求
- TLSConfig：安全传输层协议（TLS）的配置
- ReadTimeout：允许读取的最大时间
- ReadHeaderTimeout：允许读取请求头的最大时间
- WriteTimeout：允许写入的最大时间
- IdleTimeout：等待的最大时间
- MaxHeaderBytes：请求头的最大字节数
- ConnState：指定一个可选的回调函数，当客户端连接发生变化时调用
- ErrorLog：指定一个可选的日志记录器，用于接收程序的意外行为和底层系统错误；如果未设置或为`nil`则默认以日志包的标准日志记录器完成（也就是在控制台输出）

2、 ListenAndServe：

```go
func (srv *Server) ListenAndServe() error {
    addr := srv.Addr
    if addr == "" {
        addr = ":http"
    }
    ln, err := net.Listen("tcp", addr)
    if err != nil {
        return err
    }
    return srv.Serve(tcpKeepAliveListener{ln.(*net.TCPListener)})
}
```

开始监听服务，监听 TCP 网络地址，Addr 和调用应用程序处理连接上的请求。

我们在源码中看到`Addr`是调用我们在`&http.Server`中设置的参数，因此我们在设置时要用`&`，我们要改变参数的值，因为我们`ListenAndServe`和其他一些方法需要用到`&http.Server`中的参数，他们是相互影响的。

3、 `http.ListenAndServe`和 [连载一](https://segmentfault.com/a/1190000013297625#articleHeader5) 的`r.Run()`有区别吗？

我们看看`r.Run`的实现：

```go
func (engine *Engine) Run(addr ...string) (err error) {
    defer func() { debugPrintError(err) }()

    address := resolveAddress(addr)
    debugPrint("Listening and serving HTTP on %s\n", address)
    err = http.ListenAndServe(address, engine)
    return
}
```

通过分析源码，得知**本质上没有区别**，同时也得知了启动`gin`时的监听 debug 信息在这里输出。

4、 为什么 Demo 里会有`WARNING`？

首先我们可以看下`Default()`的实现

```go
// Default returns an Engine instance with the Logger and Recovery middleware already attached.
func Default() *Engine {
	debugPrintWARNINGDefault()
	engine := New()
	engine.Use(Logger(), Recovery())
	return engine
}
```

大家可以看到默认情况下，已经附加了日志、恢复中间件的引擎实例。并且在开头调用了`debugPrintWARNINGDefault()`，而它的实现就是输出该行日志

```go
func debugPrintWARNINGDefault() {
	debugPrint(`[WARNING] Creating an Engine instance with the Logger and Recovery middleware already attached.
`)
}
```

而另外一个`Running in "debug" mode. Switch to "release" mode in production.`，是运行模式原因，并不难理解，已在配置文件的管控下 :-)，运维人员随时就可以修改它的配置。

5、 Demo 的`router.GET`等路由规则可以不写在`main`包中吗？

我们发现`router.GET`等路由规则，在 Demo 中被编写在了`main`包中，感觉很奇怪，我们去抽离这部分逻辑！

在`go-gin-example`下`routers`目录新建`router.go`文件，写入内容：

```go
package routers

import (
    "github.com/gin-gonic/gin"

    "github.com/EDDYCJY/go-gin-example/pkg/setting"
)

func InitRouter() *gin.Engine {
    r := gin.New()

    r.Use(gin.Logger())

    r.Use(gin.Recovery())

    gin.SetMode(setting.RunMode)

    r.GET("/test", func(c *gin.Context) {
        c.JSON(200, gin.H{
            "message": "test",
        })
    })

    return r
}
```

修改`main.go`的文件内容：

```go
package main

import (
	"fmt"
	"net/http"

	"github.com/EDDYCJY/go-gin-example/routers"
	"github.com/EDDYCJY/go-gin-example/pkg/setting"
)

func main() {
	router := routers.InitRouter()

	s := &http.Server{
		Addr:           fmt.Sprintf(":%d", setting.HTTPPort),
		Handler:        router,
		ReadTimeout:    setting.ReadTimeout,
		WriteTimeout:   setting.WriteTimeout,
		MaxHeaderBytes: 1 << 20,
	}

	s.ListenAndServe()
}
```

当前目录结构：

```
go-gin-example/
├── conf
│   └── app.ini
├── main.go
├── middleware
├── models
│   └── models.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       └── pagination.go
├── routers
│   └── router.go
├── runtime
```

重启服务，执行 `curl 127.0.0.1:8000/test`查看是否正确返回。

下一节，我们将以我们的 Demo 为起点进行修改，开始编码！

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-02-12-api-02.md
================================================
---

title:      "「连载三」Gin搭建Blog API's （二）"
date:       2018-02-12 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- [Gin](https://github.com/gin-gonic/gin)：Golang 的一个微框架，性能极佳。
- [beego-validation](https://github.com/astaxie/beego/tree/master/validation)：本节采用的 beego 的表单验证库，[中文文档](https://beego.me/docs/mvc/controller/validation.md)。
- [gorm](https://github.com/jinzhu/gorm)，对开发人员友好的 ORM 框架，[英文文档](http://gorm.io/docs/)
- [com](https://github.com/Unknwon/com)，一个小而美的工具包。

## 本文目标

- 完成博客的标签类接口定义和编写

## 定义接口

本节正是编写标签的逻辑，我们想一想，一般接口为增删改查是基础的，那么我们定义一下接口吧！

- 获取标签列表：GET("/tags")
- 新建标签：POST("/tags")
- 更新指定标签：PUT("/tags/:id")
- 删除指定标签：DELETE("/tags/:id")

---

## 编写路由空壳

开始编写路由文件逻辑，在`routers`下新建`api`目录，我们当前是第一个 API 大版本，因此在`api`下新建`v1`目录，再新建`tag.go`文件，写入内容：

```go
package v1

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

//获取多个文章标签
func GetTags(c *gin.Context) {
}

//新增文章标签
func AddTag(c *gin.Context) {
}

//修改文章标签
func EditTag(c *gin.Context) {
}

//删除文章标签
func DeleteTag(c *gin.Context) {
}
```

## 注册路由

我们打开`routers`下的`router.go`文件，修改文件内容为：

```go
package routers

import (
    "github.com/gin-gonic/gin"

    "gin-blog/routers/api/v1"
    "gin-blog/pkg/setting"
)

func InitRouter() *gin.Engine {
    r := gin.New()

    r.Use(gin.Logger())

    r.Use(gin.Recovery())

    gin.SetMode(setting.RunMode)

    apiv1 := r.Group("/api/v1")
    {
        //获取标签列表
        apiv1.GET("/tags", v1.GetTags)
        //新建标签
        apiv1.POST("/tags", v1.AddTag)
        //更新指定标签
        apiv1.PUT("/tags/:id", v1.EditTag)
        //删除指定标签
        apiv1.DELETE("/tags/:id", v1.DeleteTag)
    }

    return r
}
```

当前目录结构：

```
gin-blog/
├── conf
│   └── app.ini
├── main.go
├── middleware
├── models
│   └── models.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       └── pagination.go
├── routers
│   ├── api
│   │   └── v1
│   │       └── tag.go
│   └── router.go
├── runtime
```

## 检验路由是否注册成功

回到命令行，执行`go run main.go`，检查路由规则是否注册成功。

```
$ go run main.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /api/v1/tags              --> gin-blog/routers/api/v1.GetTags (3 handlers)
[GIN-debug] POST   /api/v1/tags              --> gin-blog/routers/api/v1.AddTag (3 handlers)
[GIN-debug] PUT    /api/v1/tags/:id          --> gin-blog/routers/api/v1.EditTag (3 handlers)
[GIN-debug] DELETE /api/v1/tags/:id          --> gin-blog/routers/api/v1.DeleteTag (3 handlers)
```

运行成功，那么我们愉快的**开始编写我们的接口**吧！

## 下载依赖包

---

首先我们要拉取`validation`的依赖包，在后面的接口里会使用到表单验证

```
$ go get -u github.com/astaxie/beego/validation
```

## 编写标签列表的 models 逻辑

创建`models`目录下的`tag.go`，写入文件内容：

```go
package models

type Tag struct {
    Model

    Name string `json:"name"`
    CreatedBy string `json:"created_by"`
    ModifiedBy string `json:"modified_by"`
    State int `json:"state"`
}

func GetTags(pageNum int, pageSize int, maps interface {}) (tags []Tag) {
    db.Where(maps).Offset(pageNum).Limit(pageSize).Find(&tags)

    return
}

func GetTagTotal(maps interface {}) (count int){
    db.Model(&Tag{}).Where(maps).Count(&count)

    return
}
```

1. 我们创建了一个`Tag struct{}`，用于`Gorm`的使用。并给予了附属属性`json`，这样子在`c.JSON`的时候就会自动转换格式，非常的便利

2. 可能会有的初学者看到`return`，而后面没有跟着变量，会不理解；其实你可以看到在函数末端，我们已经显示声明了返回值，这个变量在函数体内也可以直接使用，因为他在一开始就被声明了

3. 有人会疑惑`db`是哪里来的；因为在同个`models`包下，因此`db *gorm.DB`是可以直接使用的

## 编写标签列表的路由逻辑

打开`routers`目录下 v1 版本的`tag.go`，第一我们先编写**获取标签列表的接口**

修改文件内容：

```go
package v1

import (
    "net/http"

    "github.com/gin-gonic/gin"
    //"github.com/astaxie/beego/validation"
    "github.com/Unknwon/com"

    "gin-blog/pkg/e"
    "gin-blog/models"
    "gin-blog/pkg/util"
    "gin-blog/pkg/setting"
)

//获取多个文章标签
func GetTags(c *gin.Context) {
    name := c.Query("name")

    maps := make(map[string]interface{})
    data := make(map[string]interface{})

    if name != "" {
        maps["name"] = name
    }

    var state int = -1
    if arg := c.Query("state"); arg != "" {
        state = com.StrTo(arg).MustInt()
        maps["state"] = state
    }

    code := e.SUCCESS

    data["lists"] = models.GetTags(util.GetPage(c), setting.PageSize, maps)
    data["total"] = models.GetTagTotal(maps)

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : data,
    })
}

//新增文章标签
func AddTag(c *gin.Context) {
}

//修改文章标签
func EditTag(c *gin.Context) {
}

//删除文章标签
func DeleteTag(c *gin.Context) {
}
```

1. `c.Query`可用于获取`?name=test&state=1`这类 URL 参数，而`c.DefaultQuery`则支持设置一个默认值
2. `code`变量使用了`e`模块的错误编码，这正是先前规划好的错误码，方便排错和识别记录
3. `util.GetPage`保证了各接口的`page`处理是一致的
4. `c *gin.Context`是`Gin`很重要的组成部分，可以理解为上下文，它允许我们在中间件之间传递变量、管理流、验证请求的 JSON 和呈现 JSON 响应

在本机执行`curl 127.0.0.1:8000/api/v1/tags`，正确的返回值为`{"code":200,"data":{"lists":[],"total":0},"msg":"ok"}`，若存在问题请结合 gin 结果进行拍错。

在获取标签列表接口中，我们可以根据`name`、`state`、`page`来筛选查询条件，分页的步长可通过`app.ini`进行配置，以`lists`、`total`的组合返回达到分页效果。

## 编写新增标签的 models 逻辑

接下来我们编写**新增标签**的接口

打开`models`目录下的`tag.go`，修改文件（增加 2 个方法）：

```go
...
func ExistTagByName(name string) bool {
    var tag Tag
    db.Select("id").Where("name = ?", name).First(&tag)
    if tag.ID > 0 {
        return true
    }

    return false
}

func AddTag(name string, state int, createdBy string) bool{
    db.Create(&Tag {
        Name : name,
        State : state,
        CreatedBy : createdBy,
    })

    return true
}
...
```

## 编写新增标签的路由逻辑

打开`routers`目录下的`tag.go`，修改文件（变动 AddTag 方法）：

```go
package v1

import (
    "log"
    "net/http"

    "github.com/gin-gonic/gin"
    "github.com/astaxie/beego/validation"
    "github.com/Unknwon/com"

    "gin-blog/pkg/e"
    "gin-blog/models"
    "gin-blog/pkg/util"
    "gin-blog/pkg/setting"
)

...

//新增文章标签
func AddTag(c *gin.Context) {
    name := c.Query("name")
    state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()
    createdBy := c.Query("created_by")

    valid := validation.Validation{}
    valid.Required(name, "name").Message("名称不能为空")
    valid.MaxSize(name, 100, "name").Message("名称最长为100字符")
    valid.Required(createdBy, "created_by").Message("创建人不能为空")
    valid.MaxSize(createdBy, 100, "created_by").Message("创建人最长为100字符")
    valid.Range(state, 0, 1, "state").Message("状态只允许0或1")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        if ! models.ExistTagByName(name) {
            code = e.SUCCESS
            models.AddTag(name, state, createdBy)
        } else {
            code = e.ERROR_EXIST_TAG
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}
...
```

用`Postman`用 POST 访问`http://127.0.0.1:8000/api/v1/tags?name=1&state=1&created_by=test`，查看`code`是否返回`200`及`blog_tag`表中是否有值，有值则正确。

## 编写 models callbacks

但是这个时候大家会发现，我明明新增了标签，但`created_on`居然没有值，那做修改标签的时候`modified_on`会不会也存在这个问题？

为了解决这个问题，我们需要打开`models`目录下的`tag.go`文件，修改文件内容（修改包引用和增加 2 个方法）：

```go
package models

import (
    "time"

    "github.com/jinzhu/gorm"
)

...

func (tag *Tag) BeforeCreate(scope *gorm.Scope) error {
    scope.SetColumn("CreatedOn", time.Now().Unix())

    return nil
}

func (tag *Tag) BeforeUpdate(scope *gorm.Scope) error {
    scope.SetColumn("ModifiedOn", time.Now().Unix())

    return nil
}
```

重启服务，再在用`Postman`用 POST 访问`http://127.0.0.1:8000/api/v1/tags?name=2&state=1&created_by=test`，发现`created_on`已经有值了！

**在这几段代码中，涉及到知识点：**

这属于`gorm`的`Callbacks`，可以将回调方法定义为模型结构的指针，在创建、更新、查询、删除时将被调用，如果任何回调返回错误，gorm 将停止未来操作并回滚所有更改。

`gorm`所支持的回调方法：

- 创建：BeforeSave、BeforeCreate、AfterCreate、AfterSave
- 更新：BeforeSave、BeforeUpdate、AfterUpdate、AfterSave
- 删除：BeforeDelete、AfterDelete
- 查询：AfterFind

---

## 编写其余接口的路由逻辑

接下来，我们一口气把剩余的两个接口（EditTag、DeleteTag）完成吧

打开`routers`目录下 v1 版本的`tag.go`文件，修改内容：

```go
...

//修改文章标签
func EditTag(c *gin.Context) {
    id := com.StrTo(c.Param("id")).MustInt()
    name := c.Query("name")
    modifiedBy := c.Query("modified_by")

    valid := validation.Validation{}

    var state int = -1
    if arg := c.Query("state"); arg != "" {
        state = com.StrTo(arg).MustInt()
        valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
    }

    valid.Required(id, "id").Message("ID不能为空")
    valid.Required(modifiedBy, "modified_by").Message("修改人不能为空")
    valid.MaxSize(modifiedBy, 100, "modified_by").Message("修改人最长为100字符")
    valid.MaxSize(name, 100, "name").Message("名称最长为100字符")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        code = e.SUCCESS
        if models.ExistTagByID(id) {
            data := make(map[string]interface{})
            data["modified_by"] = modifiedBy
            if name != "" {
                data["name"] = name
            }
            if state != -1 {
                data["state"] = state
            }

            models.EditTag(id, data)
        } else {
            code = e.ERROR_NOT_EXIST_TAG
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}

//删除文章标签
func DeleteTag(c *gin.Context) {
    id := com.StrTo(c.Param("id")).MustInt()

    valid := validation.Validation{}
    valid.Min(id, 1, "id").Message("ID必须大于0")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        code = e.SUCCESS
        if models.ExistTagByID(id) {
            models.DeleteTag(id)
        } else {
            code = e.ERROR_NOT_EXIST_TAG
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}
```

## 编写其余接口的 models 逻辑

打开`models`下的`tag.go`，修改文件内容：

```go
...

func ExistTagByID(id int) bool {
    var tag Tag
    db.Select("id").Where("id = ?", id).First(&tag)
    if tag.ID > 0 {
        return true
    }

    return false
}

func DeleteTag(id int) bool {
    db.Where("id = ?", id).Delete(&Tag{})

    return true
}

func EditTag(id int, data interface {}) bool {
    db.Model(&Tag{}).Where("id = ?", id).Updates(data)

    return true
}
...
```

## 验证功能

重启服务，用 Postman

- PUT 访问 http://127.0.0.1:8000/api/v1/tags/1?name=edit1&state=0&modified_by=edit1 ，查看 code 是否返回 200
- DELETE 访问 http://127.0.0.1:8000/api/v1/tags/1 ，查看 code 是否返回 200

至此，Tag 的 API's 完成，下一节我们将开始 Article 的 API's 编写！

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-02-13-api-03.md
================================================
---

title:      "「连载四」Gin搭建Blog API's （三）"
date:       2018-02-13 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- [Gin](https://github.com/gin-gonic/gin)：Golang 的一个微框架，性能极佳。
- [beego-validation](https://github.com/astaxie/beego/tree/master/validation)：本节采用的 beego 的表单验证库，[中文文档](https://beego.me/docs/mvc/controller/validation.md)。
- [gorm](https://github.com/jinzhu/gorm)，对开发人员友好的 ORM 框架，[英文文档](http://gorm.io/docs/)
- [com](https://github.com/Unknwon/com)，一个小而美的工具包。

## 本文目标

- 完成博客的文章类接口定义和编写

## 定义接口

本节编写文章的逻辑，我们定义一下接口吧！

- 获取文章列表：GET("/articles")
- 获取指定文章：POST("/articles/:id")
- 新建文章：POST("/articles")
- 更新指定文章：PUT("/articles/:id")
- 删除指定文章：DELETE("/articles/:id")

## 编写路由逻辑

在`routers`的 v1 版本下，新建`article.go`文件，写入内容：

```go
package v1

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

//获取单个文章
func GetArticle(c *gin.Context) {
}

//获取多个文章
func GetArticles(c *gin.Context) {
}

//新增文章
func AddArticle(c *gin.Context) {
}

//修改文章
func EditArticle(c *gin.Context) {
}

//删除文章
func DeleteArticle(c *gin.Context) {
}
```

我们打开`routers`下的`router.go`文件，修改文件内容为：

```go
package routers

import (
    "github.com/gin-gonic/gin"

    "github.com/EDDYCJY/go-gin-example/routers/api/v1"
    "github.com/EDDYCJY/go-gin-example/pkg/setting"
)

func InitRouter() *gin.Engine {
    ...
    apiv1 := r.Group("/api/v1")
    {
        ...
        //获取文章列表
        apiv1.GET("/articles", v1.GetArticles)
        //获取指定文章
        apiv1.GET("/articles/:id", v1.GetArticle)
        //新建文章
        apiv1.POST("/articles", v1.AddArticle)
        //更新指定文章
        apiv1.PUT("/articles/:id", v1.EditArticle)
        //删除指定文章
        apiv1.DELETE("/articles/:id", v1.DeleteArticle)
    }

    return r
}
```

当前目录结构：

```
go-gin-example/
├── conf
│   └── app.ini
├── main.go
├── middleware
├── models
│   ├── models.go
│   └── tag.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       └── pagination.go
├── routers
│   ├── api
│   │   └── v1
│   │       ├── article.go
│   │       └── tag.go
│   └── router.go
├── runtime

```

在基础的路由规则配置结束后，我们**开始编写我们的接口**吧！

---

##编写 models 逻辑
创建`models`目录下的`article.go`，写入文件内容：

```go
package models

import (
    "github.com/jinzhu/gorm"

    "time"
)

type Article struct {
    Model

    TagID int `json:"tag_id" gorm:"index"`
    Tag   Tag `json:"tag"`

    Title string `json:"title"`
    Desc string `json:"desc"`
    Content string `json:"content"`
    CreatedBy string `json:"created_by"`
    ModifiedBy string `json:"modified_by"`
    State int `json:"state"`
}


func (article *Article) BeforeCreate(scope *gorm.Scope) error {
    scope.SetColumn("CreatedOn", time.Now().Unix())

    return nil
}

func (article *Article) BeforeUpdate(scope *gorm.Scope) error {
    scope.SetColumn("ModifiedOn", time.Now().Unix())

    return nil
}
```

我们创建了一个`Article struct {}`，与`Tag`不同的是，`Article`多了几项，如下：

1. `gorm:index`，用于声明这个字段为索引，如果你使用了自动迁移功能则会有所影响，在不使用则无影响
2. `Tag`字段，实际是一个嵌套的`struct`，它利用`TagID`与`Tag`模型相互关联，在执行查询的时候，能够达到`Article`、`Tag`关联查询的功能
3. `time.Now().Unix()` 返回当前的时间戳

接下来，请确保已对上一章节的内容通读且了解，由于逻辑偏差不会太远，我们本节直接编写这五个接口

---

打开`models`目录下的`article.go`，修改文件内容：

```go
package models

import (
    "time"

    "github.com/jinzhu/gorm"
)

type Article struct {
    Model

    TagID int `json:"tag_id" gorm:"index"`
    Tag   Tag `json:"tag"`

    Title string `json:"title"`
    Desc string `json:"desc"`
    Content string `json:"content"`
    CreatedBy string `json:"created_by"`
    ModifiedBy string `json:"modified_by"`
    State int `json:"state"`
}


func ExistArticleByID(id int) bool {
    var article Article
    db.Select("id").Where("id = ?", id).First(&article)

    if article.ID > 0 {
        return true
    }

    return false
}

func GetArticleTotal(maps interface {}) (count int){
    db.Model(&Article{}).Where(maps).Count(&count)

    return
}

func GetArticles(pageNum int, pageSize int, maps interface {}) (articles []Article) {
    db.Preload("Tag").Where(maps).Offset(pageNum).Limit(pageSize).Find(&articles)

    return
}

func GetArticle(id int) (article Article) {
    db.Where("id = ?", id).First(&article)
    db.Model(&article).Related(&article.Tag)

    return
}

func EditArticle(id int, data interface {}) bool {
    db.Model(&Article{}).Where("id = ?", id).Updates(data)

    return true
}

func AddArticle(data map[string]interface {}) bool {
    db.Create(&Article {
        TagID : data["tag_id"].(int),
        Title : data["title"].(string),
        Desc : data["desc"].(string),
        Content : data["content"].(string),
        CreatedBy : data["created_by"].(string),
        State : data["state"].(int),
    })

    return true
}

func DeleteArticle(id int) bool {
    db.Where("id = ?", id).Delete(Article{})

    return true
}

func (article *Article) BeforeCreate(scope *gorm.Scope) error {
    scope.SetColumn("CreatedOn", time.Now().Unix())

    return nil
}

func (article *Article) BeforeUpdate(scope *gorm.Scope) error {
    scope.SetColumn("ModifiedOn", time.Now().Unix())

    return nil
}
```

在这里，我们拿出三点不同来讲，如下：

**1、 我们的`Article`是如何关联到`Tag`？**

```go
func GetArticle(id int) (article Article) {
    db.Where("id = ?", id).First(&article)
    db.Model(&article).Related(&article.Tag)

    return
}
```

能够达到关联，首先是`gorm`本身做了大量的约定俗成

- `Article`有一个结构体成员是`TagID`，就是外键。`gorm`会通过类名+ID 的方式去找到这两个类之间的关联关系
- `Article`有一个结构体成员是`Tag`，就是我们嵌套在`Article`里的`Tag`结构体，我们可以通过`Related`进行关联查询

**2、 `Preload`是什么东西，为什么查询可以得出每一项的关联`Tag`？**

```go
func GetArticles(pageNum int, pageSize int, maps interface {}) (articles []Article) {
    db.Preload("Tag").Where(maps).Offset(pageNum).Limit(pageSize).Find(&articles)

    return
}
```

`Preload`就是一个预加载器，它会执行两条 SQL，分别是`SELECT * FROM blog_articles;`和`SELECT * FROM blog_tag WHERE id IN (1,2,3,4);`，那么在查询出结构后，`gorm`内部处理对应的映射逻辑，将其填充到`Article`的`Tag`中，会特别方便，并且避免了循环查询

那么有没有别的办法呢，大致是两种

- `gorm`的`Join`
- 循环`Related`

综合之下，还是`Preload`更好，如果你有更优的方案，欢迎说一下 :)

**3、 `v.(I)` 是什么？**

`v`表示一个接口值，`I`表示接口类型。这个实际就是 Golang 中的**类型断言**，用于判断一个接口值的实际类型是否为某个类型，或一个非接口值的类型是否实现了某个接口类型

---

打开`routers`目录下 v1 版本的`article.go`文件，修改文件内容：

```go
package v1

import (
    "net/http"
    "log"

    "github.com/gin-gonic/gin"
    "github.com/astaxie/beego/validation"
    "github.com/unknwon/com"

    "github.com/EDDYCJY/go-gin-example/models"
    "github.com/EDDYCJY/go-gin-example/pkg/e"
    "github.com/EDDYCJY/go-gin-example/pkg/setting"
    "github.com/EDDYCJY/go-gin-example/pkg/util"
)

//获取单个文章
func GetArticle(c *gin.Context) {
    id := com.StrTo(c.Param("id")).MustInt()

    valid := validation.Validation{}
    valid.Min(id, 1, "id").Message("ID必须大于0")

    code := e.INVALID_PARAMS
    var data interface {}
    if ! valid.HasErrors() {
        if models.ExistArticleByID(id) {
            data = models.GetArticle(id)
            code = e.SUCCESS
        } else {
            code = e.ERROR_NOT_EXIST_ARTICLE
        }
    } else {
        for _, err := range valid.Errors {
            log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : data,
    })
}

//获取多个文章
func GetArticles(c *gin.Context) {
    data := make(map[string]interface{})
    maps := make(map[string]interface{})
    valid := validation.Validation{}

    var state int = -1
    if arg := c.Query("state"); arg != "" {
        state = com.StrTo(arg).MustInt()
        maps["state"] = state

        valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
    }

    var tagId int = -1
    if arg := c.Query("tag_id"); arg != "" {
        tagId = com.StrTo(arg).MustInt()
        maps["tag_id"] = tagId

        valid.Min(tagId, 1, "tag_id").Message("标签ID必须大于0")
    }

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        code = e.SUCCESS

        data["lists"] = models.GetArticles(util.GetPage(c), setting.PageSize, maps)
        data["total"] = models.GetArticleTotal(maps)

    } else {
        for _, err := range valid.Errors {
            log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : data,
    })
}

//新增文章
func AddArticle(c *gin.Context) {
    tagId := com.StrTo(c.Query("tag_id")).MustInt()
    title := c.Query("title")
    desc := c.Query("desc")
    content := c.Query("content")
    createdBy := c.Query("created_by")
    state := com.StrTo(c.DefaultQuery("state", "0")).MustInt()

    valid := validation.Validation{}
    valid.Min(tagId, 1, "tag_id").Message("标签ID必须大于0")
    valid.Required(title, "title").Message("标题不能为空")
    valid.Required(desc, "desc").Message("简述不能为空")
    valid.Required(content, "content").Message("内容不能为空")
    valid.Required(createdBy, "created_by").Message("创建人不能为空")
    valid.Range(state, 0, 1, "state").Message("状态只允许0或1")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        if models.ExistTagByID(tagId) {
            data := make(map[string]interface {})
            data["tag_id"] = tagId
            data["title"] = title
            data["desc"] = desc
            data["content"] = content
            data["created_by"] = createdBy
            data["state"] = state

            models.AddArticle(data)
            code = e.SUCCESS
        } else {
            code = e.ERROR_NOT_EXIST_TAG
        }
    } else {
        for _, err := range valid.Errors {
            log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]interface{}),
    })
}

//修改文章
func EditArticle(c *gin.Context) {
    valid := validation.Validation{}

    id := com.StrTo(c.Param("id")).MustInt()
    tagId := com.StrTo(c.Query("tag_id")).MustInt()
    title := c.Query("title")
    desc := c.Query("desc")
    content := c.Query("content")
    modifiedBy := c.Query("modified_by")

    var state int = -1
    if arg := c.Query("state"); arg != "" {
        state = com.StrTo(arg).MustInt()
        valid.Range(state, 0, 1, "state").Message("状态只允许0或1")
    }

    valid.Min(id, 1, "id").Message("ID必须大于0")
    valid.MaxSize(title, 100, "title").Message("标题最长为100字符")
    valid.MaxSize(desc, 255, "desc").Message("简述最长为255字符")
    valid.MaxSize(content, 65535, "content").Message("内容最长为65535字符")
    valid.Required(modifiedBy, "modified_by").Message("修改人不能为空")
    valid.MaxSize(modifiedBy, 100, "modified_by").Message("修改人最长为100字符")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        if models.ExistArticleByID(id) {
            if models.ExistTagByID(tagId) {
                data := make(map[string]interface {})
                if tagId > 0 {
                    data["tag_id"] = tagId
                }
                if title != "" {
                    data["title"] = title
                }
                if desc != "" {
                    data["desc"] = desc
                }
                if content != "" {
                    data["content"] = content
                }

                data["modified_by"] = modifiedBy

                models.EditArticle(id, data)
                code = e.SUCCESS
            } else {
                code = e.ERROR_NOT_EXIST_TAG
            }
        } else {
            code = e.ERROR_NOT_EXIST_ARTICLE
        }
    } else {
        for _, err := range valid.Errors {
            log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}

//删除文章
func DeleteArticle(c *gin.Context) {
    id := com.StrTo(c.Param("id")).MustInt()

    valid := validation.Validation{}
    valid.Min(id, 1, "id").Message("ID必须大于0")

    code := e.INVALID_PARAMS
    if ! valid.HasErrors() {
        if models.ExistArticleByID(id) {
            models.DeleteArticle(id)
            code = e.SUCCESS
        } else {
            code = e.ERROR_NOT_EXIST_ARTICLE
        }
    } else {
        for _, err := range valid.Errors {
            log.Printf("err.key: %s, err.message: %s", err.Key, err.Message)
        }
    }

    c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : make(map[string]string),
    })
}
```

当前目录结构：

```
go-gin-example/
├── conf
│   └── app.ini
├── main.go
├── middleware
├── models
│   ├── article.go
│   ├── models.go
│   └── tag.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       └── pagination.go
├── routers
│   ├── api
│   │   └── v1
│   │       ├── article.go
│   │       └── tag.go
│   └── router.go
├── runtime
```

## 验证功能

我们重启服务，执行`go run main.go`，检查控制台输出结果

```
$ go run main.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /api/v1/tags              --> gin-blog/routers/api/v1.GetTags (3 handlers)
[GIN-debug] POST   /api/v1/tags              --> gin-blog/routers/api/v1.AddTag (3 handlers)
[GIN-debug] PUT    /api/v1/tags/:id          --> gin-blog/routers/api/v1.EditTag (3 handlers)
[GIN-debug] DELETE /api/v1/tags/:id          --> gin-blog/routers/api/v1.DeleteTag (3 handlers)
[GIN-debug] GET    /api/v1/articles          --> gin-blog/routers/api/v1.GetArticles (3 handlers)
[GIN-debug] GET    /api/v1/articles/:id      --> gin-blog/routers/api/v1.GetArticle (3 handlers)
[GIN-debug] POST   /api/v1/articles          --> gin-blog/routers/api/v1.AddArticle (3 handlers)
[GIN-debug] PUT    /api/v1/articles/:id      --> gin-blog/routers/api/v1.EditArticle (3 handlers)
[GIN-debug] DELETE /api/v1/articles/:id      --> gin-blog/routers/api/v1.DeleteArticle (3 handlers)
```

使用`Postman`检验接口是否正常，在这里大家可以选用合适的参数传递方式，此处为了方便展示我选用了 GET/Param 传参的方式，而后期会改为 POST。

- POST：http://127.0.0.1:8000/api/v1/articles?tag_id=1&title=test1&desc=test-desc&content=test-content&created_by=test-created&state=1
- GET：http://127.0.0.1:8000/api/v1/articles
- GET：http://127.0.0.1:8000/api/v1/articles/1
- PUT：http://127.0.0.1:8000/api/v1/articles/1?tag_id=1&title=test-edit1&desc=test-desc-edit&content=test-content-edit&modified_by=test-created-edit&state=0
- DELETE：http://127.0.0.1:8000/api/v1/articles/1

至此，我们的 API's 编写就到这里，下一节我们将介绍另外的一些技巧！

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-02-14-jwt.md
================================================
---

title:      "「连载五」使用 JWT 进行身份校验"
date:       2018-02-14 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- JWT

## 本文目标

在前面几节中，我们已经基本的完成了 API's 的编写，但是，还存在一些非常严重的问题，例如，我们现在的 API 是可以随意调用的，这显然还不安全全，在本文中我们通过 [jwt-go](https://github.com/dgrijalva/jwt-go) （[GoDoc](https://godoc.org/github.com/dgrijalva/jwt-go)）的方式来简单解决这个问题。

## 下载依赖包

首先，我们下载 jwt-go 的依赖包，如下：

```
go get -u github.com/dgrijalva/jwt-go
```

## 编写 jwt 工具包

我们需要编写一个`jwt`的工具包，我们在`pkg`下的`util`目录新建`jwt.go`，写入文件内容：

```go
package util

import (
	"time"

	jwt "github.com/dgrijalva/jwt-go"

	"github.com/EDDYCJY/go-gin-example/pkg/setting"
)

var jwtSecret = []byte(setting.JwtSecret)

type Claims struct {
	Username string `json:"username"`
	Password string `json:"password"`
	jwt.StandardClaims
}

func GenerateToken(username, password string) (string, error) {
	nowTime := time.Now()
	expireTime := nowTime.Add(3 * time.Hour)

	claims := Claims{
		username,
		password,
		jwt.StandardClaims {
			ExpiresAt : expireTime.Unix(),
			Issuer : "gin-blog",
		},
	}

	tokenClaims := jwt.NewWithClaims(jwt.SigningMethodHS256, claims)
	token, err := tokenClaims.SignedString(jwtSecret)

	return token, err
}

func ParseToken(token string) (*Claims, error) {
	tokenClaims, err := jwt.ParseWithClaims(token, &Claims{}, func(token *jwt.Token) (interface{}, error) {
		return jwtSecret, nil
	})

	if tokenClaims != nil {
		if claims, ok := tokenClaims.Claims.(*Claims); ok && tokenClaims.Valid {
			return claims, nil
		}
	}

	return nil, err
}
```

在这个工具包，我们涉及到

- `NewWithClaims(method SigningMethod, claims Claims)`，`method`对应着`SigningMethodHMAC struct{}`，其包含`SigningMethodHS256`、`SigningMethodHS384`、`SigningMethodHS512`三种`crypto.Hash`方案
- `func (t *Token) SignedString(key interface{})` 该方法内部生成签名字符串，再用于获取完整、已签名的`token`
- `func (p *Parser) ParseWithClaims` 用于解析鉴权的声明，[方法内部](https://gowalker.org/github.com/dgrijalva/jwt-go#Parser_ParseWithClaims)主要是具体的解码和校验的过程，最终返回`*Token`
- `func (m MapClaims) Valid()` 验证基于时间的声明`exp, iat, nbf`，注意如果没有任何声明在令牌中，仍然会被认为是有效的。并且对于时区偏差没有计算方法

有了`jwt`工具包，接下来我们要编写要用于`Gin`的中间件，我们在`middleware`下新建`jwt`目录，新建`jwt.go`文件，写入内容：

```go
package jwt

import (
	"time"
	"net/http"

	"github.com/gin-gonic/gin"

	"github.com/EDDYCJY/go-gin-example/pkg/util"
	"github.com/EDDYCJY/go-gin-example/pkg/e"
)

func JWT() gin.HandlerFunc {
	return func(c *gin.Context) {
		var code int
		var data interface{}

		code = e.SUCCESS
		token := c.Query("token")
		if token == "" {
			code = e.INVALID_PARAMS
		} else {
			claims, err := util.ParseToken(token)
			if err != nil {
				code = e.ERROR_AUTH_CHECK_TOKEN_FAIL
			} else if time.Now().Unix() > claims.ExpiresAt {
				code = e.ERROR_AUTH_CHECK_TOKEN_TIMEOUT
			}
		}

		if code != e.SUCCESS {
			c.JSON(http.StatusUnauthorized, gin.H{
		        "code" : code,
		        "msg" : e.GetMsg(code),
		        "data" : data,
		    })

		    c.Abort()
		    return
		}

		c.Next()
	}
}
```

## 如何获取`Token`

那么我们如何调用它呢，我们还要获取`Token`呢？

1、 我们要新增一个获取`Token`的 API

在`models`下新建`auth.go`文件，写入内容：

```go
package models

type Auth struct {
	ID int `gorm:"primary_key" json:"id"`
	Username string `json:"username"`
	Password string `json:"password"`
}

func CheckAuth(username, password string) bool {
	var auth Auth
	db.Select("id").Where(Auth{Username : username, Password : password}).First(&auth)
	if auth.ID > 0 {
		return true
	}

	return false
}
```

在`routers`下的`api`目录新建`auth.go`文件，写入内容：

```go
package api

import (
	"log"
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/astaxie/beego/validation"

	"github.com/EDDYCJY/go-gin-example/pkg/e"
	"github.com/EDDYCJY/go-gin-example/pkg/util"
	"github.com/EDDYCJY/go-gin-example/models"
)

type auth struct {
	Username string `valid:"Required; MaxSize(50)"`
	Password string `valid:"Required; MaxSize(50)"`
}

func GetAuth(c *gin.Context) {
	username := c.Query("username")
	password := c.Query("password")

	valid := validation.Validation{}
	a := auth{Username: username, Password: password}
	ok, _ := valid.Valid(&a)

	data := make(map[string]interface{})
	code := e.INVALID_PARAMS
	if ok {
		isExist := models.CheckAuth(username, password)
		if isExist {
			token, err := util.GenerateToken(username, password)
			if err != nil {
				code = e.ERROR_AUTH_TOKEN
			} else {
				data["token"] = token

				code = e.SUCCESS
			}

		} else {
			code = e.ERROR_AUTH
		}
	} else {
		for _, err := range valid.Errors {
            log.Println(err.Key, err.Message)
        }
	}

	c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : data,
    })
}
```

我们打开`routers`目录下的`router.go`文件，修改文件内容（新增获取 token 的方法）：

```go
package routers

import (
    "github.com/gin-gonic/gin"

    "github.com/EDDYCJY/go-gin-example/routers/api"
    "github.com/EDDYCJY/go-gin-example/routers/api/v1"
    "github.com/EDDYCJY/go-gin-example/pkg/setting"
)

func InitRouter() *gin.Engine {
    r := gin.New()

    r.Use(gin.Logger())

    r.Use(gin.Recovery())

    gin.SetMode(setting.RunMode)

    r.GET("/auth", api.GetAuth)

    apiv1 := r.Group("/api/v1")
    {
        ...
    }

    return r
}
```

## 验证`Token`

获取`token`的 API 方法就到这里啦，让我们来测试下是否可以正常使用吧！

重启服务后，用`GET`方式访问`http://127.0.0.1:8000/auth?username=test&password=test123456`，查看返回值是否正确

```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJwYXNzd29yZCI6InRlc3QxMjM0NTYiLCJleHAiOjE1MTg3MjAwMzcsImlzcyI6Imdpbi1ibG9nIn0.-kK0V9E06qTHOzupQM_gHXAGDB3EJtJS4H5TTCyWwW8"
  },
  "msg": "ok"
}
```

我们有了`token`的 API，也调用成功了

## 将中间件接入`Gin`

2、 接下来我们将中间件接入到`Gin`的访问流程中

我们打开`routers`目录下的`router.go`文件，修改文件内容（新增引用包和中间件引用）

```go
package routers

import (
    "github.com/gin-gonic/gin"

    "github.com/EDDYCJY/go-gin-example/routers/api"
    "github.com/EDDYCJY/go-gin-example/routers/api/v1"
    "github.com/EDDYCJY/go-gin-example/pkg/setting"
    "github.com/EDDYCJY/go-gin-example/middleware/jwt"
)

func InitRouter() *gin.Engine {
    r := gin.New()

    r.Use(gin.Logger())

    r.Use(gin.Recovery())

    gin.SetMode(setting.RunMode)

    r.GET("/auth", api.GetAuth)

    apiv1 := r.Group("/api/v1")
    apiv1.Use(jwt.JWT())
    {
        ...
    }

    return r
}
```

当前目录结构：

```
go-gin-example/
├── conf
│   └── app.ini
├── main.go
├── middleware
│   └── jwt
│       └── jwt.go
├── models
│   ├── article.go
│   ├── auth.go
│   ├── models.go
│   └── tag.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       ├── jwt.go
│       └── pagination.go
├── routers
│   ├── api
│   │   ├── auth.go
│   │   └── v1
│   │       ├── article.go
│   │       └── tag.go
│   └── router.go
├── runtime
```

到这里，我们的`JWT`编写就完成啦！

## 验证功能

我们来测试一下，再次访问

- http://127.0.0.1:8000/api/v1/articles
- http://127.0.0.1:8000/api/v1/articles?token=23131

正确的反馈应该是

```json
{
  "code": 400,
  "data": null,
  "msg": "请求参数错误"
}

{
  "code": 20001,
  "data": null,
  "msg": "Token鉴权失败"
}

```

我们需要访问`http://127.0.0.1:8000/auth?username=test&password=test123456`，得到`token`

```json
{
  "code": 200,
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ1c2VybmFtZSI6InRlc3QiLCJwYXNzd29yZCI6InRlc3QxMjM0NTYiLCJleHAiOjE1MTg3MjQ2OTMsImlzcyI6Imdpbi1ibG9nIn0.KSBY6TeavV_30kfmP7HWLRYKP5TPEDgHtABe9HCsic4"
  },
  "msg": "ok"
}
```

再用包含`token`的 URL 参数去访问我们的应用 API，

访问`http://127.0.0.1:8000/api/v1/articles?token=eyJhbGci...`，检查接口返回值

```json
{
  "code": 200,
  "data": {
    "lists": [
      {
        "id": 2,
        "created_on": 1518700920,
        "modified_on": 0,
        "tag_id": 1,
        "tag": {
          "id": 1,
          "created_on": 1518684200,
          "modified_on": 0,
          "name": "tag1",
          "created_by": "",
          "modified_by": "",
          "state": 0
        },
        "content": "test-content",
        "created_by": "test-created",
        "modified_by": "",
        "state": 0
      }
    ],
    "total": 1
  },
  "msg": "ok"
}
```

返回正确，至此我们的`jwt-go`在`Gin`中的验证就完成了！

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-02-15-log.md
================================================
---

title:      "「连载六」编写一个简单的文件日志"
date:       2018-02-15 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- 自定义 log。

## 本文目标

在上一节中，我们解决了 API's 可以任意访问的问题，那么我们现在还有一个问题，就是我们的日志，都是输出到控制台上的，这显然对于一个项目来说是不合理的，因此我们这一节简单封装`log`库，使其支持简单的文件日志！

## 新建`logging`包

我们在`pkg`下新建`logging`目录，新建`file.go`和`log.go`文件，写入内容：

### 编写`file`文件

**1、 file.go：**

```go
package logging

import (
	"os"
	"time"
	"fmt"
	"log"
)

var (
	LogSavePath = "runtime/logs/"
	LogSaveName = "log"
	LogFileExt = "log"
	TimeFormat = "20060102"
)

func getLogFilePath() string {
	return fmt.Sprintf("%s", LogSavePath)
}

func getLogFileFullPath() string {
	prefixPath := getLogFilePath()
	suffixPath := fmt.Sprintf("%s%s.%s", LogSaveName, time.Now().Format(TimeFormat), LogFileExt)

	return fmt.Sprintf("%s%s", prefixPath, suffixPath)
}

func openLogFile(filePath string) *os.File {
	_, err := os.Stat(filePath)
	switch {
		case os.IsNotExist(err):
			mkDir()
		case os.IsPermission(err):
			log.Fatalf("Permission :%v", err)
	}

	handle, err := os.OpenFile(filePath, os.O_APPEND | os.O_CREATE | os.O_WRONLY, 0644)
	if err != nil {
		log.Fatalf("Fail to OpenFile :%v", err)
	}

	return handle
}

func mkDir() {
	dir, _ := os.Getwd()
	err := os.MkdirAll(dir + "/" + getLogFilePath(), os.ModePerm)
	if err != nil {
		panic(err)
	}
}
```

- `os.Stat`：返回文件信息结构描述文件。如果出现错误，会返回`*PathError`

```go
type PathError struct {
    Op   string
    Path string
    Err  error
}
```

- `os.IsNotExist`：能够接受`ErrNotExist`、`syscall`的一些错误，它会返回一个布尔值，能够得知文件不存在或目录不存在
- `os.IsPermission`：能够接受`ErrPermission`、`syscall`的一些错误，它会返回一个布尔值，能够得知权限是否满足
- `os.OpenFile`：调用文件，支持传入文件名称、指定的模式调用文件、文件权限，返回的文件的方法可以用于 I/O。如果出现错误，则为`*PathError`。

```go
const (
    // Exactly one of O_RDONLY, O_WRONLY, or O_RDWR must be specified.
    O_RDONLY int = syscall.O_RDONLY // 以只读模式打开文件
    O_WRONLY int = syscall.O_WRONLY // 以只写模式打开文件
    O_RDWR   int = syscall.O_RDWR   // 以读写模式打开文件
    // The remaining values may be or'ed in to control behavior.
    O_APPEND int = syscall.O_APPEND // 在写入时将数据追加到文件中
    O_CREATE int = syscall.O_CREAT  // 如果不存在，则创建一个新文件
    O_EXCL   int = syscall.O_EXCL   // 使用O_CREATE时，文件必须不存在
    O_SYNC   int = syscall.O_SYNC   // 同步IO
    O_TRUNC  int = syscall.O_TRUNC  // 如果可以，打开时
)
```

- `os.Getwd`：返回与当前目录对应的根路径名
- `os.MkdirAll`：创建对应的目录以及所需的子目录，若成功则返回`nil`，否则返回`error`
- `os.ModePerm`：`const`定义`ModePerm FileMode = 0777`

### 编写`log`文件

**2、log.go**

```go
package logging

import (
	"log"
	"os"
	"runtime"
	"path/filepath"
	"fmt"
)

type Level int

var (
	F *os.File

	DefaultPrefix = ""
	DefaultCallerDepth = 2

	logger *log.Logger
	logPrefix = ""
	levelFlags = []string{"DEBUG", "INFO", "WARN", "ERROR", "FATAL"}
)

const (
	DEBUG Level = iota
	INFO
	WARNING
	ERROR
	FATAL
)

func init() {
	filePath := getLogFileFullPath()
	F = openLogFile(filePath)

	logger = log.New(F, DefaultPrefix, log.LstdFlags)
}

func Debug(v ...interface{}) {
	setPrefix(DEBUG)
	logger.Println(v)
}

func Info(v ...interface{}) {
	setPrefix(INFO)
	logger.Println(v)
}

func Warn(v ...interface{}) {
	setPrefix(WARNING)
	logger.Println(v)
}

func Error(v ...interface{}) {
	setPrefix(ERROR)
	logger.Println(v)
}

func Fatal(v ...interface{}) {
	setPrefix(FATAL)
	logger.Fatalln(v)
}

func setPrefix(level Level) {
	_, file, line, ok := runtime.Caller(DefaultCallerDepth)
	if ok {
		logPrefix = fmt.Sprintf("[%s][%s:%d]", levelFlags[level], filepath.Base(file), line)
	} else {
		logPrefix = fmt.Sprintf("[%s]", levelFlags[level])
	}

	logger.SetPrefix(logPrefix)
}

```

- `log.New`：创建一个新的日志记录器。`out`定义要写入日志数据的`IO`句柄。`prefix`定义每个生成的日志行的开头。`flag`定义了日志记录属性

```go
func New(out io.Writer, prefix string, flag int) *Logger {
    return &Logger{out: out, prefix: prefix, flag: flag}
}
```

- `log.LstdFlags`：日志记录的格式属性之一，其余的选项如下

```go
const (
    Ldate         = 1 << iota     // the date in the local time zone: 2009/01/23
    Ltime                         // the time in the local time zone: 01:23:23
    Lmicroseconds                 // microsecond resolution: 01:23:23.123123.  assumes Ltime.
    Llongfile                     // full file name and line number: /a/b/c/d.go:23
    Lshortfile                    // final file name element and line number: d.go:23. overrides Llongfile
    LUTC                          // if Ldate or Ltime is set, use UTC rather than the local time zone
    LstdFlags     = Ldate | Ltime // initial values for the standard logger
)
```

当前目录结构：

```
gin-blog/
├── conf
│   └── app.ini
├── main.go
├── middleware
│   └── jwt
│       └── jwt.go
├── models
│   ├── article.go
│   ├── auth.go
│   ├── models.go
│   └── tag.go
├── pkg
│   ├── e
│   │   ├── code.go
│   │   └── msg.go
│   ├── logging
│   │   ├── file.go
│   │   └── log.go
│   ├── setting
│   │   └── setting.go
│   └── util
│       ├── jwt.go
│       └── pagination.go
├── routers
│   ├── api
│   │   ├── auth.go
│   │   └── v1
│   │       ├── article.go
│   │       └── tag.go
│   └── router.go
├── runtime

```

我们自定义的`logging`包，已经基本完成了，接下来让它接入到我们的项目之中吧。我们打开先前包含`log`包的代码，如下：

1. 打开`routers`目录下的`article.go`、`tag.go`、`auth.go`。
2. 将`log`包的引用删除，修改引用我们自己的日志包为`github.com/EDDYCJY/go-gin-example/pkg/logging`。
3. 将原本的`log.Println(...)`改为`logging.Info(...)`。

例如`auth.go`文件的修改内容：

```go
package api

import (
	"net/http"

	"github.com/gin-gonic/gin"
	"github.com/astaxie/beego/validation"

	"github.com/EDDYCJY/go-gin-example/pkg/e"
	"github.com/EDDYCJY/go-gin-example/pkg/util"
	"github.com/EDDYCJY/go-gin-example/models"
	"github.com/EDDYCJY/go-gin-example/pkg/logging"
)
...
func GetAuth(c *gin.Context) {
	...
	code := e.INVALID_PARAMS
	if ok {
		...
	} else {
	    for _, err := range valid.Errors {
                logging.Info(err.Key, err.Message)
            }
	}

	c.JSON(http.StatusOK, gin.H{
        "code" : code,
        "msg" : e.GetMsg(code),
        "data" : data,
    })
}
```

## 验证功能

修改文件后，重启服务，我们来试试吧！

获取到 API 的 Token 后，我们故意传错误 URL 参数给接口，如：`http://127.0.0.1:8000/api/v1/articles?tag_id=0&state=9999999&token=eyJhbG..`

然后我们到`$GOPATH/gin-blog/runtime/logs`查看日志：

```
$ tail -f log20180216.log
[INFO][article.go:79]2018/02/16 18:33:12 [state 状态只允许0或1]
[INFO][article.go:79]2018/02/16 18:33:42 [state 状态只允许0或1]
[INFO][article.go:79]2018/02/16 18:33:42 [tag_id 标签ID必须大于0]
[INFO][article.go:79]2018/02/16 18:38:39 [state 状态只允许0或1]
[INFO][article.go:79]2018/02/16 18:38:39 [tag_id 标签ID必须大于0]
```

日志结构一切正常，我们的记录模式都为`Info`，因此前缀是对的，并且我们是入参有问题，也把错误记录下来了，这样排错就很方便了！

至此，本节就完成了，这只是一个简单的扩展，实际上我们线上项目要使用的文件日志，是更复杂一些，开动你的大脑 举一反三吧！

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-03-15-reload-http.md
================================================
---

title:      "「连载七」优雅的重启服务"
date:       2018-03-15 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 信号量的了解。
- 应用热更新。

## 本文目标

在前面编写案例代码时，我相信你会想到，每次更新完代码，更新完配置文件后，就直接这么 `ctrl+c` 真的没问题吗，`ctrl+c`到底做了些什么事情呢？

在这一节中我们简单讲述 `ctrl+c` 背后的**信号**以及如何在`Gin`中**优雅的重启服务**，也就是对 `HTTP` 服务进行热更新。

## ctrl + c

> 内核在某些情况下发送信号，比如在进程往一个已经关闭的管道写数据时会产生`SIGPIPE`信号

在终端执行特定的组合键可以使系统发送特定的信号给此进程，完成一系列的动作

| 命令      | 信号    | 含义                                                                                                    |
| --------- | ------- | ------------------------------------------------------------------------------------------------------- |
| ctrl + c  | SIGINT  | 强制进程结束                                                                                            |
| ctrl + z  | SIGTSTP | 任务中断，进程挂起                                                                                      |
| ctrl + \  | SIGQUIT | 进程结束 和 `dump core`                                                                                 |
| ctrl + d  |         | EOF                                                                                                     |
|           | SIGHUP  | 终止收到该信号的进程。若程序中没有捕捉该信号，当收到该信号时，进程就会退出（常用于 重启、重新加载进程） |

因此在我们执行`ctrl + c`关闭`gin`服务端时，**会强制进程结束，导致正在访问的用户等出现问题**

常见的 `kill -9 pid` 会发送 `SIGKILL` 信号给进程，也是类似的结果

### 信号

本段中反复出现**信号**是什么呢？

信号是 `Unix` 、类 `Unix` 以及其他 `POSIX` 兼容的操作系统中进程间通讯的一种有限制的方式

它是一种异步的通知机制，用来提醒进程一个事件（硬件异常、程序执行异常、外部发出信号）已经发生。当一个信号发送给一个进程，操作系统中断了进程正常的控制流程。此时，任何非原子操作都将被中断。如果进程定义了信号的处理函数，那么它将被执行，否则就执行默认的处理函数

### 所有信号

```
$ kill -l
 1) SIGHUP   2) SIGINT   3) SIGQUIT  4) SIGILL   5) SIGTRAP
 6) SIGABRT  7) SIGBUS   8) SIGFPE   9) SIGKILL 10) SIGUSR1
11) SIGSEGV 12) SIGUSR2 13) SIGPIPE 14) SIGALRM 15) SIGTERM
16) SIGSTKFLT   17) SIGCHLD 18) SIGCONT 19) SIGSTOP 20) SIGTSTP
21) SIGTTIN 22) SIGTTOU 23) SIGURG  24) SIGXCPU 25) SIGXFSZ
26) SIGVTALRM   27) SIGPROF 28) SIGWINCH    29) SIGIO   30) SIGPWR
31) SIGSYS  34) SIGRTMIN    35) SIGRTMIN+1  36) SIGRTMIN+2  37) SIGRTMIN+3
38) SIGRTMIN+4  39) SIGRTMIN+5  40) SIGRTMIN+6  41) SIGRTMIN+7  42) SIGRTMIN+8
43) SIGRTMIN+9  44) SIGRTMIN+10 45) SIGRTMIN+11 46) SIGRTMIN+12 47) SIGRTMIN+13
48) SIGRTMIN+14 49) SIGRTMIN+15 50) SIGRTMAX-14 51) SIGRTMAX-13 52) SIGRTMAX-12
53) SIGRTMAX-11 54) SIGRTMAX-10 55) SIGRTMAX-9  56) SIGRTMAX-8  57) SIGRTMAX-7
58) SIGRTMAX-6  59) SIGRTMAX-5  60) SIGRTMAX-4  61) SIGRTMAX-3  62) SIGRTMAX-2
63) SIGRTMAX-1  64) SIGRTMAX
```

## 怎样算优雅

### 目的

- 不关闭现有连接（正在运行中的程序）
- 新的进程启动并替代旧进程
- 新的进程接管新的连接
- 连接要随时响应用户的请求，当用户仍在请求旧进程时要保持连接，新用户应请求新进程，不可以出现拒绝请求的情况

### 流程

1、替换可执行文件或修改配置文件

2、发送信号量 `SIGHUP`

3、拒绝新连接请求旧进程，但要保证已有连接正常

4、启动新的子进程

5、新的子进程开始 `Accet`

6、系统将新的请求转交新的子进程

7、旧进程处理完所有旧连接后正常结束

## 实现优雅重启

### endless

> Zero downtime restarts for golang HTTP and HTTPS servers. (for golang 1.3+)

我们借助 [fvbock/endless](https://github.com/fvbock/endless) 来实现 `Golang HTTP/HTTPS` 服务重新启动的零停机

`endless server` 监听以下几种信号量：

- syscall.SIGHUP：触发 `fork` 子进程和重新启动
- syscall.SIGUSR1/syscall.SIGTSTP：被监听，但不会触发任何动作
- syscall.SIGUSR2：触发 `hammerTime`
- syscall.SIGINT/syscall.SIGTERM：触发服务器关闭（会完成正在运行的请求）

`endless` 正正是依靠监听这些**信号量**，完成管控的一系列动作

#### 安装

```
go get -u github.com/fvbock/endless
```

#### 编写

打开 [gin-blog](https://github.com/EDDYCJY/go-gin-example) 的 `main.go`文件，修改文件：

```go
package main

import (
    "fmt"
    "log"
    "syscall"

    "github.com/fvbock/endless"

    "gin-blog/routers"
    "gin-blog/pkg/setting"
)

func main() {
    endless.DefaultReadTimeOut = setting.ReadTimeout
    endless.DefaultWriteTimeOut = setting.WriteTimeout
    endless.DefaultMaxHeaderBytes = 1 << 20
    endPoint := fmt.Sprintf(":%d", setting.HTTPPort)

    server := endless.NewServer(endPoint, routers.InitRouter())
    server.BeforeBegin = func(add string) {
        log.Printf("Actual pid is %d", syscall.Getpid())
    }

    err := server.ListenAndServe()
    if err != nil {
        log.Printf("Server err: %v", err)
    }
}
```

`endless.NewServer` 返回一个初始化的 `endlessServer` 对象，在 `BeforeBegin` 时输出当前进程的 `pid`，调用 `ListenAndServe` 将实际“启动”服务

#### 验证

##### **编译**

```
$ go build main.go
```

##### **执行**

```
$ ./main
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
...
Actual pid is 48601
```

启动成功后，输出了`pid`为 48601；在另外一个终端执行 `kill -1 48601` ，检验先前服务的终端效果

```
[root@localhost go-gin-example]# ./main
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:   export GIN_MODE=release
 - using code:  gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /auth                     --> ...
[GIN-debug] GET    /api/v1/tags              --> ...
...

Actual pid is 48601

...

Actual pid is 48755
48601 Received SIGTERM.
48601 [::]:8000 Listener closed.
48601 Waiting for connections to finish...
48601 Serve() returning...
Server err: accept tcp [::]:8000: use of closed network connection
```

可以看到该命令已经挂起，并且 `fork` 了新的子进程 `pid` 为 `48755`

```
48601 Received SIGTERM.
48601 [::]:8000 Listener closed.
48601 Waiting for connections to finish...
48601 Serve() returning...
Server err: accept tcp [::]:8000: use of closed network connection
```

大致意思为主进程（`pid`为 48601）接受到 `SIGTERM` 信号量，关闭主进程的监听并且等待正在执行的请求完成；这与我们先前的描述一致

##### **唤醒**

这时候在 `postman` 上再次访问我们的接口，你可以惊喜的发现，他“复活”了！

```
Actual pid is 48755
48601 Received SIGTERM.
48601 [::]:8000 Listener closed.
48601 Waiting for connections to finish...
48601 Serve() returning...
Server err: accept tcp [::]:8000: use of closed network connection


$ [GIN] 2018/03/15 - 13:00:16 | 200 |     188.096µs |   192.168.111.1 | GET      /api/v1/tags...

```

这就完成了一次正向的流转了

你想想，每次更新发布、或者修改配置文件等，只需要给该进程发送**SIGTERM 信号**，而不需要强制结束应用，是多么便捷又安全的事！

#### 问题

`endless` 热更新是采取创建子进程后，将原进程退出的方式，这点不符合守护进程的要求

### http.Server - Shutdown()

如果你的`Golang >= 1.8`，也可以考虑使用 `http.Server` 的 [Shutdown](https://golang.org/pkg/net/http/#Server.Shutdown) 方法

```go
package main

import (
    "fmt"
    "net/http"
    "context"
    "log"
    "os"
    "os/signal"
    "time"


    "gin-blog/routers"
    "gin-blog/pkg/setting"
)

func main() {
    router := routers.InitRouter()

    s := &http.Server{
        Addr:           fmt.Sprintf(":%d", setting.HTTPPort),
        Handler:        router,
        ReadTimeout:    setting.ReadTimeout,
        WriteTimeout:   setting.WriteTimeout,
        MaxHeaderBytes: 1 << 20,
    }

    go func() {
        if err := s.ListenAndServe(); err != nil {
            log.Printf("Listen: %s\n", err)
        }
    }()

    quit := make(chan os.Signal)
    signal.Notify(quit, os.Interrupt)
    <- quit

    log.Println("Shutdown Server ...")

    ctx, cancel := context.WithTimeout(context.Background(), 5 * time.Second)
    defer cancel()
    if err := s.Shutdown(ctx); err != nil {
        log.Fatal("Server Shutdown:", err)
    }

    log.Println("Server exiting")
}
```

## 小结

在日常的服务中，优雅的重启（热更新）是非常重要的一环。而 `Golang` 在 `HTTP` 服务方面的热更新也有不少方案了，我们应该根据实际应用场景挑选最合适的

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

### 拓展阅读

- [manners](https://github.com/braintree/manners)
- [graceful](https://github.com/tylerb/graceful)
- [grace](https://github.com/facebookgo/grace)
- [plugin: new package for loading plugins · golang/go@0cbb12f · GitHub](https://github.com/golang/go/commit/0cbb12f0bbaeb3893b3d011fdb1a270291747ab0)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-03-18-swagger.md
================================================
---

title:      "「连载八」为它加上Swagger"
date:       2018-03-18 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- Swagger

## 本文目标

一个好的 `API's`，必然离不开一个好的`API`文档，如果要开发纯手写 `API` 文档，不存在的（很难持续维护），因此我们要自动生成接口文档。

## 安装 swag

```
$ go get -u github.com/swaggo/swag/cmd/swag@v1.6.5
```

若 `$GOROOT/bin` 没有加入`$PATH`中，你需要执行将其可执行文件移动到`$GOBIN`下

```
mv $GOPATH/bin/swag /usr/local/go/bin
```

### 验证是否安装成功

检查 \$GOBIN 下是否有 swag 文件，如下：

```
$ swag -v
swag version v1.6.5
```

## 安装 gin-swagger

```
$ go get -u github.com/swaggo/gin-swagger@v1.2.0 
$ go get -u github.com/swaggo/files
$ go get -u github.com/alecthomas/template
```

注：若无科学上网，请务必配置 Go modules proxy。

## 初始化

### 编写 API 注释

`Swagger` 中需要将相应的注释或注解编写到方法上，再利用生成器自动生成说明文件

`gin-swagger` 给出的范例：

```go
// @Summary Add a new pet to the store
// @Description get string by ID
// @Accept  json
// @Produce  json
// @Param   some_id     path    int     true        "Some ID"
// @Success 200 {string} string	"ok"
// @Failure 400 {object} web.APIError "We need ID!!"
// @Failure 404 {object} web.APIError "Can not find ID"
// @Router /testapi/get-string-by-int/{some_id} [get]
```

我们可以参照 `Swagger` 的注解规范和范例去编写

```go
// @Summary 新增文章标签
// @Produce  json
// @Param name query string true "Name"
// @Param state query int false "State"
// @Param created_by query int false "CreatedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags [post]
func AddTag(c *gin.Context) {
```

```go
// @Summary 修改文章标签
// @Produce  json
// @Param id path int true "ID"
// @Param name query string true "ID"
// @Param state query int false "State"
// @Param modified_by query string true "ModifiedBy"
// @Success 200 {string} json "{"code":200,"data":{},"msg":"ok"}"
// @Router /api/v1/tags/{id} [put]
func EditTag(c *gin.Context) {
```

参考的注解请参见 [go-gin-example](https://github.com/EDDYCJY/go-gin-example)。以确保获取最新的 swag 语法

### 路由

在完成了注解的编写后，我们需要针对 swagger 新增初始化动作和对应的路由规则，才可以使用。打开 routers/router.go 文件，新增内容如下：

```go
package routers

import (
	...

	_ "github.com/EDDYCJY/go-gin-example/docs"

	...
)

// InitRouter initialize routing information
func InitRouter() *gin.Engine {
	...
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	...
	apiv1 := r.Group("/api/v1")
	apiv1.Use(jwt.JWT())
	{
		...
	}

	return r
}
```

### 生成

我们进入到`gin-blog`的项目根目录中，执行初始化命令

```
[$ gin-blog]# swag init
2018/03/13 23:32:10 Generate swagger docs....
2018/03/13 23:32:10 Generate general API Info
2018/03/13 23:32:10 create docs.go at  docs/docs.go

```

完毕后会在项目根目录下生成`docs`

```
docs/
├── docs.go
└── swagger
    ├── swagger.json
    └── swagger.yaml

```

我们可以检查 `docs.go` 文件中的 `doc` 变量，详细记载中我们文件中所编写的注解和说明
![image](https://image.eddycjy.com/37ae10e1714c63899a55d49c19af0860.png)

### 验证

大功告成，访问一下 `http://127.0.0.1:8000/swagger/index.html`， 查看 `API` 文档生成是否正确

![image](https://image.eddycjy.com/703b677c6756129c33b5308c1655a35c.png)

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-03-24-golang-docker.md
================================================
---

title:      "「连载九」将Golang应用部署到Docker"
date:       2018-03-24 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- Go + Docker

## 本文目标

将我们的 `go-gin-example` 应用部署到一个 Docker 里，你需要先准备好如下东西：

- 你需要安装好 `docker`。
- 如果上外网比较吃力，需要配好镜像源。

## Docker

在这里简单介绍下 Docker，建议深入学习

![image](https://timgsa.baidu.com/timg?image&quality=80&size=b9999_10000&sec=1521800047226&di=28b2764fccca8a943aea7d79ad8aed98&imgtype=0&src=http%3A%2F%2Fwww.cww.net.cn%2FupLoadFile%2F2014%2F6%2F13%2F201461382247734.png)

Docker 是一个开源的轻量级容器技术，让开发者可以打包他们的应用以及应用运行的上下文环境到一个可移植的镜像中，然后发布到任何支持 Docker 的系统上运行。 通过容器技术，在几乎没有性能开销的情况下，Docker 为应用提供了一个隔离运行环境

- 简化配置
- 代码流水线管理
- 提高开发效率
- 隔离应用
- 快速、持续部署

---

接下来我们正式开始对项目进行 `docker` 的所需处理和编写，每一个大标题为步骤大纲

## Golang

### 一、编写 Dockerfile

在 `go-gin-example` 项目根目录创建 Dockerfile 文件，写入内容

```
FROM golang:latest

ENV GOPROXY https://goproxy.cn,direct
WORKDIR $GOPATH/src/github.com/EDDYCJY/go-gin-example
COPY . $GOPATH/src/github.com/EDDYCJY/go-gin-example
RUN go build .

EXPOSE 8000
ENTRYPOINT ["./go-gin-example"]
```

#### 作用

`golang:latest` 镜像为基础镜像，将工作目录设置为 `$GOPATH/src/go-gin-example`，并将当前上下文目录的内容复制到 `$GOPATH/src/go-gin-example` 中

在进行 `go build` 编译完毕后，将容器启动程序设置为 `./go-gin-example`，也就是我们所编译的可执行文件

注意 `go-gin-example` 在 `docker` 容器里编译，并没有在宿主机现场编译

#### 说明

Dockerfile 文件是用于定义 Docker 镜像生成流程的配置文件，文件内容是一条条指令，每一条指令构建一层，因此每一条指令的内容，就是描述该层应当如何构建；这些指令应用于基础镜像并最终创建一个新的镜像

你可以认为用于快速创建自定义的 Docker 镜像

**1、 FROM**

指定基础镜像（必须有的指令，并且必须是第一条指令）

**2、 WORKDIR**

格式为 `WORKDIR` <工作目录路径>

使用 `WORKDIR` 指令可以来**指定工作目录**（或者称为当前目录），以后各层的当前目录就被改为指定的目录，如果目录不存在，`WORKDIR` 会帮你建立目录

**3、COPY**

格式：

    COPY <源路径>... <目标路径>
    COPY ["<源路径1>",... "<目标路径>"]

`COPY` 指令将从构建上下文目录中 <源路径> 的文件/目录**复制**到新的一层的镜像内的 <目标路径> 位置

**4、RUN**

用于执行命令行命令

格式：`RUN` <命令>

**5、EXPOSE**

格式为 `EXPOSE` <端口 1> [<端口 2>...]

`EXPOSE` 指令是**声明运行时容器提供服务端口，这只是一个声明**，在运行时并不会因为这个声明应用就会开启这个端口的服务

在 Dockerfile 中写入这样的声明有两个好处

- 帮助镜像使用者理解这个镜像服务的守护端口，以方便配置映射
- 运行时使用随机端口映射时，也就是 `docker run -P` 时，会自动随机映射 `EXPOSE` 的端口

**6、ENTRYPOINT**

`ENTRYPOINT` 的格式和 `RUN` 指令格式一样，分为两种格式

- `exec` 格式：

```
<ENTRYPOINT> "<CMD>"
```

- `shell` 格式：

```
ENTRYPOINT [ "curl", "-s", "http://ip.cn" ]
```

`ENTRYPOINT` 指令是**指定容器启动程序及参数**

### 二、构建镜像

`go-gin-example` 的项目根目录下**执行** `docker build -t gin-blog-docker .`

该命令作用是创建/构建镜像，`-t` 指定名称为 `gin-blog-docker`，`.` 构建内容为当前上下文目录

```
$ docker build -t gin-blog-docker .
Sending build context to Docker daemon 96.39 MB
Step 1/6 : FROM golang:latest
 ---> d632bbfe5767
Step 2/6 : WORKDIR $GOPATH/src/github.com/EDDYCJY/go-gin-example
 ---> 56294f978c5d
Removing intermediate container e112997b995d
Step 3/6 : COPY . $GOPATH/src/github.com/EDDYCJY/go-gin-example
 ---> 3b60960120cf
Removing intermediate container 63e310b3f60c
Step 4/6 : RUN go build .
 ---> Running in 52648a431450
go: downloading github.com/gin-gonic/gin v1.3.0
go: downloading github.com/go-ini/ini v1.32.1-0.20180214101753-32e4be5f41bb
go: downloading github.com/swaggo/gin-swagger v1.0.1-0.20190110070702-0c6fcfd3c7f3
...
 ---> 7bfbeb301fea
Removing intermediate container 52648a431450
Step 5/6 : EXPOSE 8000
 ---> Running in 98f5b387d1bb
 ---> b65bd4076c65
Removing intermediate container 98f5b387d1bb
Step 6/6 : ENTRYPOINT ./go-gin-example
 ---> Running in c4f6cdeb667b
 ---> d8a109c7697c
Removing intermediate container c4f6cdeb667b
Successfully built d8a109c7697c
```

### 三、验证镜像

查看所有的镜像，确定刚刚构建的 `gin-blog-docker` 镜像是否存在

```
$ docker images
REPOSITORY              TAG                 IMAGE ID            CREATED              SIZE
gin-blog-docker         latest              d8a109c7697c        About a minute ago   946 MB
docker.io/golang        latest              d632bbfe5767        8 days ago           779 MB
...
```

### 四、创建并运行一个新容器

执行命令 `docker run -p 8000:8000 gin-blog-docker`

```
$ docker run -p 8000:8000 gin-blog-docker
dial tcp 127.0.0.1:3306: connect: connection refused
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

...
Actual pid is 1

```

运行成功，你以为大功告成了吗？

你想太多了，仔细看看控制台的输出了一条错误 `dial tcp 127.0.0.1:3306: connect: connection refused`

我们研判一下，发现是 `Mysql` 的问题，接下来第二项我们将解决这个问题

## Mysql

### 一、拉取镜像

从 `Docker` 的公共仓库 `Dockerhub` 下载 `MySQL` 镜像（国内建议配个镜像）

```
$ docker pull mysql
```

### 二、创建并运行一个新容器

运行 `Mysql` 容器，并设置执行成功后返回容器 ID

```
$ docker run --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=rootroot -d mysql
8c86ac986da4922492934b6fe074254c9165b8ee3e184d29865921b0fef29e64
```

#### 连接 Mysql

初始化的 `Mysql` 应该如图

![image](https://i.loli.net/2018/03/23/5ab4caab04cf1.png)

## Golang + Mysql

### 一、删除镜像

由于原本的镜像存在问题，我们需要删除它，此处有几种做法

- 删除原本有问题的镜像，重新构建一个新镜像
- 重新构建一个不同 `name`、`tag` 的新镜像

删除原本的有问题的镜像，`-f` 是强制删除及其关联状态

若不执行 `-f`，你需要执行 `docker ps -a` 查到所关联的容器，将其 `rm` 解除两者依赖关系

```
$ docker rmi -f gin-blog-docker
Untagged: gin-blog-docker:latest
Deleted: sha256:d8a109c7697c3c2d9b4de7dbb49669d10106902122817b6467a031706bc52ab4
Deleted: sha256:b65bd4076c65a3c24029ca4def3b3f37001ff7c9eca09e2590c4d29e1e23dce5
Deleted: sha256:7bfbeb301fea9d8912a4b7c43e4bb8b69bdc57f0b416b372bfb6510e476a7dee
Deleted: sha256:3b60960120cf619181c1762cdc1b8ce318b8c815e056659809252dd321bcb642
Deleted: sha256:56294f978c5dfcfa4afa8ad033fd76b755b7ecb5237c6829550741a4d2ce10bc
```

### 二、修改配置文件

将项目的配置文件 `conf/app.ini`，内容修改为

```ini
#debug or release
RUN_MODE = debug

[app]
PAGE_SIZE = 10
JWT_SECRET = 233

[server]
HTTP_PORT = 8000
READ_TIMEOUT = 60
WRITE_TIMEOUT = 60

[database]
TYPE = mysql
USER = root
PASSWORD = rootroot
HOST = mysql:3306
NAME = blog
TABLE_PREFIX = blog_

```

### 三、重新构建镜像

重复先前的步骤，回到 `gin-blog` 的项目根目录下**执行** `docker build -t gin-blog-docker .`

### 四、创建并运行一个新容器

## 关联

Q：我们需要将 `Golang` 容器和 `Mysql` 容器关联起来，那么我们需要怎么做呢？

A：增加命令 `--link mysql:mysql` 让 `Golang` 容器与 `Mysql` 容器互联；通过 `--link`，**可以在容器内直接使用其关联的容器别名进行访问**，而不通过 IP，但是`--link`只能解决单机容器间的关联，在分布式多机的情况下，需要通过别的方式进行连接

## 运行

执行命令 `docker run --link mysql:mysql -p 8000:8000 gin-blog-docker`

```
$ docker run --link mysql:mysql -p 8000:8000 gin-blog-docker
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)
...
Actual pid is 1
```

## 结果

检查启动输出、接口测试、数据库内数据，均正常；我们的 `Golang` 容器和 `Mysql` 容器成功关联运行，大功告成 :)

---

## Review

### 思考

虽然应用已经能够跑起来了

但如果对 `Golang` 和 `Docker` 有一定的了解，我希望你能够想到至少 2 个问题

- 为什么 `gin-blog-docker` 占用空间这么大？（可用 `docker ps -as | grep gin-blog-docker` 查看）
- `Mysql` 容器直接这么使用，数据存储到哪里去了？

### 创建超小的 Golang 镜像

Q：第一个问题，为什么这么镜像体积这么大？

A：`FROM golang:latest` 拉取的是官方 `golang` 镜像，包含 Golang 的编译和运行环境，外加一堆 GCC、build 工具，相当齐全

这是有问题的，**我们可以不在 Golang 容器中现场编译的**，压根用不到那些东西，我们只需要一个能够运行可执行文件的环境即可

#### 构建 Scratch 镜像

Scratch 镜像，简洁、小巧，基本是个空镜像

##### 一、修改 Dockerfile

```
FROM scratch

WORKDIR $GOPATH/src/github.com/EDDYCJY/go-gin-example
COPY . $GOPATH/src/github.com/EDDYCJY/go-gin-example

EXPOSE 8000
CMD ["./go-gin-example"]
```

##### 二、编译可执行文件

```
CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o go-gin-example .
```

编译所生成的可执行文件会依赖一些库，并且是动态链接。在这里因为使用的是 `scratch` 镜像，它是空镜像，因此我们需要将生成的可执行文件静态链接所依赖的库

##### 三、构建镜像

```
$ docker build -t gin-blog-docker-scratch .
Sending build context to Docker daemon 133.1 MB
Step 1/5 : FROM scratch
 --->
Step 2/5 : WORKDIR $GOPATH/src/github.com/EDDYCJY/go-gin-example
 ---> Using cache
 ---> ee07e166a638
Step 3/5 : COPY . $GOPATH/src/github.com/EDDYCJY/go-gin-example
 ---> 1489a0693d51
Removing intermediate container e3e9efc0fe4d
Step 4/5 : EXPOSE 8000
 ---> Running in b5630de5544a
 ---> 6993e9f8c944
Removing intermediate container b5630de5544a
Step 5/5 : CMD ./go-gin-example
 ---> Running in eebc0d8628ae
 ---> 5310bebeb86a
Removing intermediate container eebc0d8628ae
Successfully built 5310bebeb86a
```

注意，假设你的 Golang 应用没有依赖任何的配置等文件，是可以直接把可执行文件给拷贝进去即可，其他都不必关心

这里可以有好几种解决方案

- 依赖文件统一管理挂载
- go-bindata 一下

...

因此这里如果**解决了文件依赖的问题**后，就不需要把目录给 `COPY` 进去了

##### 四、运行

```
$ docker run --link mysql:mysql -p 8000:8000 gin-blog-docker-scratch
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:	export GIN_MODE=release
 - using code:	gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /auth                     --> github.com/EDDYCJY/go-gin-example/routers/api.GetAuth (3 handlers)
...
```

成功运行，程序也正常接收请求

接下来我们再看看占用大小，执行 `docker ps -as` 命令

```
$ docker ps -as
CONTAINER ID        IMAGE                     COMMAND                  ...         SIZE
9ebdba5a8445        gin-blog-docker-scratch   "./go-gin-example"       ...     0 B (virtual 132 MB)
427ee79e6857        gin-blog-docker           "./go-gin-example"       ...     0 B (virtual 946 MB)
```

从结果而言，占用大小以`Scratch`镜像为基础的容器完胜，完成目标

### Mysql 挂载数据卷

倘若不做任何干涉，在每次启动一个 `Mysql` 容器时，数据库都是空的。另外容器删除之后，数据就丢失了（还有各类意外情况），非常糟糕！

#### 数据卷

数据卷 是被设计用来持久化数据的，它的生命周期独立于容器，Docker 不会在容器被删除后自动删除 数据卷，并且也不存在垃圾回收这样的机制来处理没有任何容器引用的 数据卷。如果需要在删除容器的同时移除数据卷。可以在删除容器的时候使用 `docker rm -v` 这个命令

数据卷 是一个可供一个或多个容器使用的特殊目录，它绕过 UFS，可以提供很多有用的特性：

- 数据卷 可以在容器之间共享和重用

- 对 数据卷 的修改会立马生效

- 对 数据卷 的更新，不会影响镜像

- 数据卷 默认会一直存在，即使容器被删除

> 注意：数据卷 的使用，类似于 Linux 下对目录或文件进行 mount，镜像中的被指定为挂载点的目录中的文件会隐藏掉，能显示看的是挂载的 数据卷。

#### 如何挂载

首先创建一个目录用于存放数据卷；示例目录 `/data/docker-mysql`，注意 `--name` 原本名称为 `mysql` 的容器，需要将其删除 `docker rm`

```
$ docker run --name mysql -p 3306:3306 -e MYSQL_ROOT_PASSWORD=rootroot -v /data/docker-mysql:/var/lib/mysql -d mysql
54611dbcd62eca33fb320f3f624c7941f15697d998f40b24ee535a1acf93ae72
```

创建成功，检查目录 `/data/docker-mysql`，下面多了不少数据库文件

#### 验证

接下来交由你进行验证，目标是创建一些测试表和数据，然后删除当前容器，重新创建的容器，数据库数据也依然存在（当然了数据卷指向要一致）

我已验证完毕，你呢？

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

### 书籍

- [Docker —— 从入门到实践](https://www.gitbook.com/book/yeasy/docker_practice/details)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-03-26-cgo.md
================================================
---

title:      "「番外」Golang 交叉编译"
date:       2018-03-26 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 跨平台编译

## 本文目标

在 [连载九](https://segmentfault.com/a/1190000013960558) 讲解**构建 Scratch 镜像**时，我们编译可执行文件用了另外一个形式的命令，如下：

```
$ CGO_ENABLED=0 GOOS=linux go build -a -installsuffix cgo -o go-gin-example .
```

我想你可能会有疑问，今天本文会针对这块进行讲解。

## 说明

我们将讲解命令各个参数的作用，希望你在阅读时，将每一项串联起来，你会发现这就是**交叉编译相关的小知识**

也就是 `Golang` 令人心动的特性之一**跨平台编译**

### 一、CGO_ENABLED

**作用：**

用于标识（声明） `cgo` 工具是否可用

**意义：**

存在交叉编译的情况时，`cgo` 工具是不可用的。在标准 go 命令的上下文环境中，交叉编译意味着程序构建环境的目标计算架构的标识与程序运行环境的目标计算架构的标识不同，或者程序构建环境的目标操作系统的标识与程序运行环境的目标操作系统的标识不同

**小结：**

结合案例来说，我们是在宿主机编译的可执行文件，而在 `Scratch` 镜像运行的可执行文件；显然两者的计算机架构、运行环境标识你无法确定它是否一致（毕竟构建的 `docker` 镜像还可以给他人使用），那么我们就要进行交叉编译，而交叉编译不支持 `cgo`，因此这里要禁用掉它

关闭 `cgo` 后，在构建过程中会忽略 `cgo` 并静态链接所有的依赖库，而开启 `cgo` 后，方式将转为动态链接

**补充：**

`golang` 是默认开启 `cgo` 工具的，可执行 `go env` 命令查看

```
$ go env
GOARCH="amd64"
GOBIN=""
GOCACHE="/root/.cache/go-build"
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
...
GCCGO="gccgo"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
...
```

### 二、GOOS

用于标识（声明）程序构建环境的目标操作系统

如：

- linux
- windows

### 三、GOARCH

用于标识（声明）程序构建环境的目标计算架构

若不设置，默认值与程序运行环境的目标计算架构一致（案例就是采用的默认值）

如：

- amd64
- 386

| 系统          | GOOS    | GOARCH |
| ------------- | ------- | ------ |
| Windows 32 位 | windows | 386    |
| Windows 64 位 | windows | amd64  |
| OS X 32 位    | darwin  | 386    |
| OS X 64 位    | darwin  | amd64  |
| Linux 32 位   | linux   | 386    |
| Linux 64 位   | linux   | amd64  |

### 四、GOHOSTOS

用于标识（声明）程序运行环境的目标操作系统

### 五、GOHOSTARCH

用于标识（声明）程序运行环境的目标计算架构

### 六、go build

#### -a

强制重新编译，简单来说，就是不利用缓存或已编译好的部分文件，直接所有包都是最新的代码重新编译和关联

#### -installsuffix

**作用：**

在软件包安装的目录中**增加后缀标识**，以保持输出与默认版本分开

**补充：**

如果使用 `-race` 标识，则后缀就会默认设置为 `-race` 标识，用于区别 `race` 和普通的版本

#### -o

指定编译后的可执行文件名称

### 小结

大部分参数指令，都有一定关联性，且与交叉编译的知识点相关，可以好好品味一下

最后可以看看 `go build help` 加深了解

```
$ go help build
usage: go build [-o output] [-i] [build flags] [packages]
...
	-a
		force rebuilding of packages that are already up-to-date.
	-n
		print the commands but do not run them.
	-p n
		the number of programs, such as build commands or
		test binaries, that can be run in parallel.
		The default is the number of CPUs available.
	-race
		enable data race detection.
		Supported only on linux/amd64, freebsd/amd64, darwin/amd64 and windows/amd64.
	-msan
		enable interoperation with memory sanitizer.
		Supported only on linux/amd64,
		and only with Clang/LLVM as the host C compiler.
	-v
		print the names of packages as they are compiled.
	-work
		print the name of the temporary work directory and
		do not delete it when exiting.
	-x
		print the commands.

	-asmflags '[pattern=]arg list'
		arguments to pass on each go tool asm invocation.
	-buildmode mode
		build mode to use. See 'go help buildmode' for more.
	-compiler name
		name of compiler to use, as in runtime.Compiler (gccgo or gc).
	-gccgoflags '[pattern=]arg list'
		arguments to pass on each gccgo compiler/linker invocation.
	-gcflags '[pattern=]arg list'
		arguments to pass on each go tool compile invocation.
	-installsuffix suffix
		a suffix to use in the name of the package installation directory,
		in order to keep output separate from default builds.
		If using the -race flag, the install suffix is automatically set to race
		or, if set explicitly, has _race appended to it. Likewise for the -msan
		flag. Using a -buildmode option that requires non-default compile flags
		has a similar effect.
	-ldflags '[pattern=]arg list'
		arguments to pass on each go tool link invocation.
	-linkshared
		link against shared libraries previously created with
		-buildmode=shared.
	-pkgdir dir
		install and load all packages from dir instead of the usual locations.
		For example, when building with a non-standard configuration,
		use -pkgdir to keep generated packages in a separate location.
	-tags 'tag list'
		a space-separated list of build tags to consider satisfied during the
		build. For more information about build tags, see the description of
		build constraints in the documentation for the go/build package.
	-toolexec 'cmd args'
		a program to use to invoke toolchain programs like vet and asm.
		For example, instead of running asm, the go command will run
		'cmd args /path/to/asm <arguments for asm>'.
...
```

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

### 书籍

- Go 并发编程实战 第二版

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-04-15-gorm-callback.md
================================================
---

title:      "「连载十」定制 GORM Callbacks"
date:       2018-04-15 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 涉及知识点

- GORM

## 本文目标

> GORM itself is powered by Callbacks, so you could fully customize GORM as you want

GORM 本身是由回调驱动的，所以我们可以根据需要完全定制 GORM，以此达到我们的目的，如下：

- 注册一个新的回调
- 删除现有的回调
- 替换现有的回调
- 注册回调的顺序

在 GORM 中包含以上四类 Callbacks，我们结合项目选用 “替换现有的回调” 来解决一个小痛点。

## 问题

在 models 目录下，我们包含 tag.go 和 article.go 两个文件，他们有一个问题，就是 BeforeCreate、BeforeUpdate 重复出现了，那难道 100 个文件，就要写一百次吗？

1、tag.go

![image](https://i.loli.net/2018/04/14/5ad20efdba409.jpg)

2、article.go

![image](https://i.loli.net/2018/04/14/5ad20ebacc4c9.jpg)

显然这是不可能的，如果先前你已经意识到这个问题，那挺 OK，但没有的话，现在开始就要改

### 解决

在这里我们通过 Callbacks 来实现功能，不需要一个个文件去编写

### 实现 Callbacks

打开 models 目录下的 models.go 文件，实现以下两个方法：

1、updateTimeStampForCreateCallback

```go
// updateTimeStampForCreateCallback will set `CreatedOn`, `ModifiedOn` when creating
func updateTimeStampForCreateCallback(scope *gorm.Scope) {
    if !scope.HasError() {
        nowTime := time.Now().Unix()
        if createTimeField, ok := scope.FieldByName("CreatedOn"); ok {
            if createTimeField.IsBlank {
                createTimeField.Set(nowTime)
            }
        }

        if modifyTimeField, ok := scope.FieldByName("ModifiedOn"); ok {
            if modifyTimeField.IsBlank {
                modifyTimeField.Set(nowTime)
            }
        }
    }
}
```

在这段方法中，会完成以下功能

- 检查是否有含有错误（db.Error）
- `scope.FieldByName` 通过 `scope.Fields()` 获取所有字段，判断当前是否包含所需字段

```go
for _, field := range scope.Fields() {
    if field.Name == name || field.DBName == name {
        return field, true
    }
    if field.DBName == dbName {
        mostMatchedField = field
    }
}
```

- `field.IsBlank` 可判断该字段的值是否为空

```go
func isBlank(value reflect.Value) bool {
    switch value.Kind() {
    case reflect.String:
        return value.Len() == 0
    case reflect.Bool:
        return !value.Bool()
    case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
        return value.Int() == 0
    case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
        return value.Uint() == 0
    case reflect.Float32, reflect.Float64:
        return value.Float() == 0
    case reflect.Interface, reflect.Ptr:
        return value.IsNil()
    }

    return reflect.DeepEqual(value.Interface(), reflect.Zero(value.Type()).Interface())
}
```

- 若为空则 `field.Set` 用于给该字段设置值，参数为 `interface{}`

2、updateTimeStampForUpdateCallback

```go
// updateTimeStampForUpdateCallback will set `ModifyTime` when updating
func updateTimeStampForUpdateCallback(scope *gorm.Scope) {
    if _, ok := scope.Get("gorm:update_column"); !ok {
        scope.SetColumn("ModifiedOn", time.Now().Unix())
    }
}
```

- `scope.Get(...)` 根据入参获取设置了字面值的参数，例如本文中是 `gorm:update_column` ，它会去查找含这个字面值的字段属性
- `scope.SetColumn(...)` 假设没有指定 `update_column` 的字段，我们默认在更新回调设置 `ModifiedOn` 的值

### 注册 Callbacks

在上面小节我已经把回调方法编写好了，接下来需要将其注册进 GORM 的钩子里，但其本身自带 Create 和 Update 回调，因此调用替换即可

在 models.go 的 init 函数中，增加以下语句

```go
db.Callback().Create().Replace("gorm:update_time_stamp", updateTimeStampForCreateCallback)
db.Callback().Update().Replace("gorm:update_time_stamp", updateTimeStampForUpdateCallback)
```

### 验证

访问 AddTag 接口，成功后检查数据库，可发现 `created_on` 和 `modified_on` 字段都为当前执行时间

访问 EditTag 接口，可发现 `modified_on` 为最后一次执行更新的时间

## 拓展

我们想到，在实际项目中硬删除是较少存在的，那么是否可以通过 Callbacks 来完成这个功能呢？

答案是可以的，我们在先前 `Model struct` 增加 `DeletedOn` 变量

```go
type Model struct {
    ID int `gorm:"primary_key" json:"id"`
    CreatedOn int `json:"created_on"`
    ModifiedOn int `json:"modified_on"`
    DeletedOn int `json:"deleted_on"`
}
```

### 实现 Callbacks

打开 models 目录下的 models.go 文件，实现以下方法：

```go
func deleteCallback(scope *gorm.Scope) {
    if !scope.HasError() {
        var extraOption string
        if str, ok := scope.Get("gorm:delete_option"); ok {
            extraOption = fmt.Sprint(str)
        }

        deletedOnField, hasDeletedOnField := scope.FieldByName("DeletedOn")

        if !scope.Search.Unscoped && hasDeletedOnField {
            scope.Raw(fmt.Sprintf(
                "UPDATE %v SET %v=%v%v%v",
                scope.QuotedTableName(),
                scope.Quote(deletedOnField.DBName),
                scope.AddToVars(time.Now().Unix()),
                addExtraSpaceIfExist(scope.CombinedConditionSql()),
                addExtraSpaceIfExist(extraOption),
            )).Exec()
        } else {
            scope.Raw(fmt.Sprintf(
                "DELETE FROM %v%v%v",
                scope.QuotedTableName(),
                addExtraSpaceIfExist(scope.CombinedConditionSql()),
                addExtraSpaceIfExist(extraOption),
            )).Exec()
        }
    }
}

func addExtraSpaceIfExist(str string) string {
    if str != "" {
        return " " + str
    }
    return ""
}
```

- `scope.Get("gorm:delete_option")` 检查是否手动指定了 delete_option
- `scope.FieldByName("DeletedOn")` 获取我们约定的删除字段，若存在则 `UPDATE` 软删除，若不存在则 `DELETE` 硬删除
- `scope.QuotedTableName()` 返回引用的表名，这个方法 GORM 会根据自身逻辑对表名进行一些处理
- `scope.CombinedConditionSql()` 返回组合好的条件 SQL，看一下方法原型很明了

```go
func (scope *Scope) CombinedConditionSql() string {
    joinSQL := scope.joinsSQL()
    whereSQL := scope.whereSQL()
    if scope.Search.raw {
        whereSQL = strings.TrimSuffix(strings.TrimPrefix(whereSQL, "WHERE ("), ")")
    }
    return joinSQL + whereSQL + scope.groupSQL() +
        scope.havingSQL() + scope.orderSQL() + scope.limitAndOffsetSQL()
}
```

- `scope.AddToVars` 该方法可以添加值作为 SQL 的参数，也可用于防范 SQL 注入

```go
func (scope *Scope) AddToVars(value interface{}) string {
    _, skipBindVar := scope.InstanceGet("skip_bindvar")

    if expr, ok := value.(*expr); ok {
        exp := expr.expr
        for _, arg := range expr.args {
            if skipBindVar {
                scope.AddToVars(arg)
            } else {
                exp = strings.Replace(exp, "?", scope.AddToVars(arg), 1)
            }
        }
        return exp
    }

    scope.SQLVars = append(scope.SQLVars, value)

    if skipBindVar {
        return "?"
    }
    return scope.Dialect().BindVar(len(scope.SQLVars))
}
```

### 注册 Callbacks

在 models.go 的 init 函数中，增加以下删除的回调

```go
db.Callback().Delete().Replace("gorm:delete", deleteCallback)
```

### 验证

重启服务，访问 DeleteTag 接口，成功后即可发现 deleted_on 字段有值

## 小结

在这一章节中，我们结合 GORM 完成了新增、更新、查询的 Callbacks，在实际项目中常常也是这么使用

毕竟，一个钩子的事，就没有必要自己手写过多不必要的代码了

（注意，增加了软删除后，先前的代码需要增加 `deleted_on` 的判断）

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

### 文档

- [gorm](http://gorm.io/docs/write_plugins.html)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-04-29-cron.md
================================================
---

title:      "「连载十一」Cron定时任务"
date:       2018-04-29 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 完成定时任务的功能

## 本文目标

在实际的应用项目中，定时任务的使用是很常见的。你是否有过 Golang 如何做定时任务的疑问，莫非是轮询，在本文中我们将结合我们的项目讲述 Cron。

## 介绍

我们将使用 [cron](https://github.com/robfig/cron) 这个包，它实现了 cron 规范解析器和任务运行器，简单来讲就是包含了定时任务所需的功能

### Cron 表达式格式

| 字段名                         | 是否必填 | 允许的值        | 允许的特殊字符 |
| ------------------------------ | -------- | --------------- | -------------- |
| 秒（Seconds）                  | Yes      | 0-59            | \* / , -       |
| 分（Minutes）                  | Yes      | 0-59            | \* / , -       |
| 时（Hours）                    | Yes      | 0-23            | \* / , -       |
| 一个月中的某天（Day of month） | Yes      | 1-31            | \* / , - ?     |
| 月（Month）                    | Yes      | 1-12 or JAN-DEC | \* / , -       |
| 星期几（Day of week）          | Yes      | 0-6 or SUN-SAT  | \* / , - ?     |

Cron 表达式表示一组时间，使用 6 个空格分隔的字段

可以留意到 Golang 的 Cron 比 Crontab 多了一个秒级，以后遇到秒级要求的时候就省事了

### Cron 特殊字符

1、星号 ( \* )

星号表示将匹配字段的所有值

2、斜线 ( / )

斜线用户 描述范围的增量，表现为 “N-MAX/x”，first-last/x 的形式，例如 3-59/15 表示此时的第三分钟和此后的每 15 分钟，到 59 分钟为止。即从 N 开始，使用增量直到该特定范围结束。它不会重复

3、逗号 ( , )

逗号用于分隔列表中的项目。例如，在 Day of week 使用“MON，WED，FRI”将意味着星期一，星期三和星期五

4、连字符 ( - )

连字符用于定义范围。例如，9 - 17 表示从上午 9 点到下午 5 点的每个小时

5、问号 ( ? )

不指定值，用于代替 “ \* ”，类似 “ \_ ” 的存在，不难理解

### 预定义的 Cron 时间表

| 输入                   | 简述                                   | 相当于          |
| ---------------------- | -------------------------------------- | --------------- |
| @yearly (or @annually) | 1 月 1 日午夜运行一次                  | 0 0 0 1 1 \*    |
| @monthly               | 每个月的午夜，每个月的第一个月运行一次 | 0 0 0 1 \* \*   |
| @weekly                | 每周一次，周日午夜运行一次             | 0 0 0 \* \* 0   |
| @daily (or @midnight)  | 每天午夜运行一次                       | 0 0 0 \* \* \*  |
| @hourly                | 每小时运行一次                         | 0 0 \* \* \* \* |

## 安装

```
$ go get -u github.com/robfig/cron
```

## 实践

在上一章节 [Gin 实践 连载十 定制 GORM Callbacks](https://segmentfault.com/a/1190000014393602) 中，我们使用了 GORM 的回调实现了软删除，同时也引入了另外一个问题

就是我怎么硬删除，我什么时候硬删除？这个往往与业务场景有关系，大致为

- 另外有一套硬删除接口
- 定时任务清理（或转移、backup）无效数据

在这里我们选用第二种解决方案来进行实践

### 编写硬删除代码

打开 models 目录下的 tag.go、article.go 文件，分别添加以下代码

1、tag.go

```go
func CleanAllTag() bool {
	db.Unscoped().Where("deleted_on != ? ", 0).Delete(&Tag{})

	return true
}
```

2、article.go

```go
func CleanAllArticle() bool {
	db.Unscoped().Where("deleted_on != ? ", 0).Delete(&Article{})

	return true
}

```

注意硬删除要使用 `Unscoped()`，这是 GORM 的约定

### 编写 Cron

在 项目根目录下新建 cron.go 文件，用于编写定时任务的代码，写入文件内容

```go
package main

import (
	"time"
	"log"

	"github.com/robfig/cron"

	"github.com/EDDYCJY/go-gin-example/models"
)

func main() {
	log.Println("Starting...")

	c := cron.New()
	c.AddFunc("* * * * * *", func() {
		log.Println("Run models.CleanAllTag...")
		models.CleanAllTag()
	})
	c.AddFunc("* * * * * *", func() {
		log.Println("Run models.CleanAllArticle...")
		models.CleanAllArticle()
	})

	c.Start()

	t1 := time.NewTimer(time.Second * 10)
	for {
		select {
		case <-t1.C:
			t1.Reset(time.Second * 10)
		}
	}
}
```

在这段程序中，我们做了如下的事情

#### cron.New()

会根据本地时间创建一个新（空白）的 Cron job runner

```go
func New() *Cron {
	return NewWithLocation(time.Now().Location())
}

// NewWithLocation returns a new Cron job runner.
func NewWithLocation(location *time.Location) *Cron {
	return &Cron{
		entries:  nil,
		add:      make(chan *Entry),
		stop:     make(chan struct{}),
		snapshot: make(chan []*Entry),
		running:  false,
		ErrorLog: nil,
		location: location,
	}
}
```

#### c.AddFunc()

AddFunc 会向 Cron job runner 添加一个 func ，以按给定的时间表运行

```go
func (c *Cron) AddJob(spec string, cmd Job) error {
	schedule, err := Parse(spec)
	if err != nil {
		return err
	}
	c.Schedule(schedule, cmd)
	return nil
}
```

会首先解析时间表，如果填写有问题会直接 err，无误则将 func 添加到 Schedule 队列中等待执行

```go
func (c *Cron) Schedule(schedule Schedule, cmd Job) {
	entry := &Entry{
		Schedule: schedule,
		Job:      cmd,
	}
	if !c.running {
		c.entries = append(c.entries, entry)
		return
	}

	c.add <- entry
}
```

3、c.Start()

在当前执行的程序中启动 Cron 调度程序。其实这里的主体是 goroutine + for + select + timer 的调度控制哦

```go
func (c *Cron) Run() {
	if c.running {
		return
	}
	c.running = true
	c.run()
}
```

#### time.NewTimer + for + select + t1.Reset

如果你是初学者，大概会有疑问，这是干嘛用的？

**（1）time.NewTimer **

会创建一个新的定时器，持续你设定的时间 d 后发送一个 channel 消息

**（2）for + select**

阻塞 select 等待 channel

**（3）t1.Reset**

会重置定时器，让它重新开始计时

注：本文适用于 “t.C 已经取走，可直接使用 Reset”。

---

总的来说，这段程序是为了阻塞主程序而编写的，希望你带着疑问来想，有没有别的办法呢？

有的，你直接 `select{}` 也可以完成这个需求 :)

## 验证

```
$ go run cron.go
2018/04/29 17:03:34 [info] replacing callback `gorm:update_time_stamp` from /Users/eddycjy/go/src/github.com/EDDYCJY/go-gin-example/models/models.go:56
2018/04/29 17:03:34 [info] replacing callback `gorm:update_time_stamp` from /Users/eddycjy/go/src/github.com/EDDYCJY/go-gin-example/models/models.go:57
2018/04/29 17:03:34 [info] replacing callback `gorm:delete` from /Users/eddycjy/go/src/github.com/EDDYCJY/go-gin-example/models/models.go:58
2018/04/29 17:03:34 Starting...
2018/04/29 17:03:35 Run models.CleanAllArticle...
2018/04/29 17:03:35 Run models.CleanAllTag...
2018/04/29 17:03:36 Run models.CleanAllArticle...
2018/04/29 17:03:36 Run models.CleanAllTag...
2018/04/29 17:03:37 Run models.CleanAllTag...
2018/04/29 17:03:37 Run models.CleanAllArticle...
```

检查输出日志正常，模拟已软删除的数据，定时任务工作 OK

## 小结

定时任务很常见，希望你通过本文能够熟知 Golang 怎么实现一个简单的定时任务调度管理

可以不依赖系统的 Crontab 设置，指不定哪一天就用上了呢

## 问题

如果你手动修改计算机的系统时间，是会导致定时任务错乱的，所以一般不要乱来。

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 02 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)


================================================
FILE: content/posts/go/gin/2018-05-27-config-upload.md
================================================
---

title:      "「连载十二」优化配置结构及实现图片上传"
date:       2018-05-27 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 重构、调整结构

## 本文目标

这个应用程序跑了那么久了，越来越大，越来越壮，仿佛我们的产品一样，现在它需要进行小范围重构了，以便于后续的使用，这非常重要。

## 前言

一天，产品经理突然跟你说文章列表，没有封面图，不够美观，！）&￥*！&）#&￥*！加一个吧，几分钟的事

你打开你的程序，分析了一波写了个清单：

- 优化配置结构（因为配置项越来越多）
- 抽离 原 logging 的 File 便于公用（logging、upload 各保有一份并不合适）
- 实现上传图片接口（需限制文件格式、大小）
- 修改文章接口（需支持封面地址参数）
- 增加 blog_article （文章）的数据库字段
- 实现 http.FileServer

嗯，你发现要较优的话，需要调整部分的应用程序结构，因为功能越来越多，原本的设计也要跟上节奏

也就是在适当的时候，及时优化

## 优化配置结构

### 一、讲解

在先前章节中，采用了直接读取 KEY 的方式去存储配置项，而本次需求中，需要增加图片的配置项，总体就有些冗余了

我们采用以下解决方法：

- 映射结构体：使用 MapTo 来设置配置参数
- 配置统管：所有的配置项统管到 setting 中

#### 映射结构体（示例）

在 go-ini 中可以采用 MapTo 的方式来映射结构体，例如：

```go
type Server struct {
	RunMode string
	HttpPort int
	ReadTimeout time.Duration
	WriteTimeout time.Duration
}

var ServerSetting = &Server{}

func main() {
    Cfg, err := ini.Load("conf/app.ini")
	if err != nil {
		log.Fatalf("Fail to parse 'conf/app.ini': %v", err)
	}

	err = Cfg.Section("server").MapTo(ServerSetting)
	if err != nil {
		log.Fatalf("Cfg.MapTo ServerSetting err: %v", err)
	}
}
```

在这段代码中，可以注意 ServerSetting 取了地址，为什么 MapTo 必须地址入参呢？

```go
// MapTo maps section to given struct.
func (s *Section) MapTo(v interface{}) error {
	typ := reflect.TypeOf(v)
	val := reflect.ValueOf(v)
	if typ.Kind() == reflect.Ptr {
		typ = typ.Elem()
		val = val.Elem()
	} else {
		return errors.New("cannot map to non-pointer struct")
	}

	return s.mapTo(val, false)
}
```

在 MapTo 中 `typ.Kind() == reflect.Ptr` 约束了必须使用指针，否则会返回 `cannot map to non-pointer struct` 的错误。这个是表面原因

更往内探究，可以认为是 `field.Set` 的原因，当执行 `val := reflect.ValueOf(v)` ，函数通过传递 `v` 拷贝创建了 `val`，但是 `val` 的改变并不能更改原始的 `v`，要想 `val` 的更改能作用到 `v`，则必须传递 `v` 的地址

显然 go-ini 里也是包含修改原始值这一项功能的，你觉得是什么原因呢？

#### 配置统管

在先前的版本中，models 和 file 的配置是在自己的文件中解析的，而其他在 setting.go 中，因此我们需要将其在 setting 中统一接管

你可能会想，直接把两者的配置项复制粘贴到 setting.go 的 init 中，一下子就完事了，搞那么麻烦？

但你在想想，先前的代码中存在多个 init 函数，执行顺序存在问题，无法达到我们的要求，你可以试试

（此处是一个基础知识点）

在 Go 中，当存在多个 init 函数时，执行顺序为：

- 相同包下的 init 函数：按照源文件编译顺序决定执行顺序（默认按文件名排序）
- 不同包下的 init 函数：按照包导入的依赖关系决定先后顺序

所以要避免多 init 的情况，**尽量由程序把控初始化的先后顺序**

### 二、落实

#### 修改配置文件

打开 conf/app.ini 将配置文件修改为大驼峰命名，另外我们增加了 5 个配置项用于上传图片的功能，4 个文件日志方面的配置项

```ini
[app]
PageSize = 10
JwtSecret = 233

RuntimeRootPath = runtime/

ImagePrefixUrl = http://127.0.0.1:8000
ImageSavePath = upload/images/
# MB
ImageMaxSize = 5
ImageAllowExts = .jpg,.jpeg,.png

LogSavePath = logs/
LogSaveName = log
LogFileExt = log
TimeFormat = 20060102

[server]
#debug or release
RunMode = debug
HttpPort = 8000
ReadTimeout = 60
WriteTimeout = 60

[database]
Type = mysql
User = root
Password = rootroot
Host = 127.0.0.1:3306
Name = blog
TablePrefix = blog_
```

#### 优化配置读取及设置初始化顺序

##### 第一步

将散落在其他文件里的配置都删掉，**统一在 setting 中处理**以及**修改 init 函数为 Setup 方法**

打开 pkg/setting/setting.go 文件，修改如下：

```go
package setting

import (
	"log"
	"time"

	"github.com/go-ini/ini"
)

type App struct {
	JwtSecret string
	PageSize int
	RuntimeRootPath string

	ImagePrefixUrl string
	ImageSavePath string
	ImageMaxSize int
	ImageAllowExts []string

	LogSavePath string
	LogSaveName string
	LogFileExt string
	TimeFormat string
}

var AppSetting = &App{}

type Server struct {
	RunMode string
	HttpPort int
	ReadTimeout time.Duration
	WriteTimeout time.Duration
}

var ServerSetting = &Server{}

type Database struct {
	Type string
	User string
	Password string
	Host string
	Name string
	TablePrefix string
}

var DatabaseSetting = &Database{}

func Setup() {
	Cfg, err := ini.Load("conf/app.ini")
	if err != nil {
		log.Fatalf("Fail to parse 'conf/app.ini': %v", err)
	}

	err = Cfg.Section("app").MapTo(AppSetting)
	if err != nil {
		log.Fatalf("Cfg.MapTo AppSetting err: %v", err)
	}

	AppSetting.ImageMaxSize = AppSetting.ImageMaxSize * 1024 * 1024

	err = Cfg.Section("server").MapTo(ServerSetting)
	if err != nil {
		log.Fatalf("Cfg.MapTo ServerSetting err: %v", err)
	}

	ServerSetting.ReadTimeout = ServerSetting.ReadTimeout * time.Second
	ServerSetting.WriteTimeout = ServerSetting.WriteTimeout * time.Second

	err = Cfg.Section("database").MapTo(DatabaseSetting)
	if err != nil {
		log.Fatalf("Cfg.MapTo DatabaseSetting err: %v", err)
	}
}
```

在这里，我们做了如下几件事：

- 编写与配置项保持一致的结构体（App、Server、Database）
- 使用 MapTo 将配置项映射到结构体上
- 对一些需特殊设置的配置项进行再赋值

**需要你去做的事：**

- 将 [models.go](https://github.com/EDDYCJY/go-gin-example/blob/a338ddec103c9506b4c7ed16d9f5386040d99b4b/models/models.go#L23)、[setting.go](https://github.com/EDDYCJY/go-gin-example/blob/a338ddec103c9506b4c7ed16d9f5386040d99b4b/pkg/setting/setting.go#L23)、[pkg/logging/log.go](https://github.com/EDDYCJY/go-gin-example/blob/a338ddec103c9506b4c7ed16d9f5386040d99b4b/pkg/logging/log.go#L32-L37) 的 init 函数修改为 Setup 方法
- 将 [models/models.go](https://github.com/EDDYCJY/go-gin-example/blob/a338ddec103c9506b4c7ed16d9f5386040d99b4b/models/models.go#L23-L39) 独立读取的 DB 配置项删除，改为统一读取 setting
- 将 [pkg/logging/file](https://github.com/EDDYCJY/go-gin-example/blob/a338ddec103c9506b4c7ed16d9f5386040d99b4b/pkg/logging/file.go#L10-L15) 独立的 LOG 配置项删除，改为统一读取 setting

这几项比较基础，并没有贴出来，我希望你可以自己动手，有问题的话可右拐 [项目地址](https://github.com/EDDYCJY/go-gin-example)

##### 第二步

在这一步我们要设置初始化的流程，打开 main.go 文件，修改内容：

```go
func main() {
	setting.Setup()
	models.Setup()
	logging.Setup()

	endless.DefaultReadTimeOut = setting.ServerSetting.ReadTimeout
	endless.DefaultWriteTimeOut = setting.ServerSetting.WriteTimeout
	endless.DefaultMaxHeaderBytes = 1 << 20
	endPoint := fmt.Sprintf(":%d", setting.ServerSetting.HttpPort)

	server := endless.NewServer(endPoint, routers.InitRouter())
	server.BeforeBegin = func(add string) {
		log.Printf("Actual pid is %d", syscall.Getpid())
	}

	err := server.ListenAndServe()
	if err != nil {
		log.Printf("Server err: %v", err)
	}
}
```

修改完毕后，就成功将多模块的初始化函数放到启动流程中了（先后顺序也可以控制）

##### 验证

在这里为止，针对本需求的配置优化就完毕了，你需要执行 `go run main.go` 验证一下你的功能是否正常哦

顺带留个基础问题，大家可以思考下

```go
ServerSetting.ReadTimeout = ServerSetting.ReadTimeout * time.Second
ServerSetting.WriteTimeout = ServerSetting.ReadTimeout * time.Second
```

若将 setting.go 文件中的这两行删除，会出现什么问题，为什么呢？

## 抽离 File

在先前版本中，在 [logging/file.go](https://github.com/EDDYCJY/go-gin-example/blob/a338ddec103c9506b4c7ed16d9f5386040d99b4b/pkg/logging/file.go) 中使用到了 os 的一些方法，我们通过前期规划发现，这部分在上传图片功能中可以复用

### 第一步

在 pkg 目录下新建 file/file.go ，写入文件内容如下：

```go
package file

import (
	"os"
	"path"
	"mime/multipart"
	"io/ioutil"
)

func GetSize(f multipart.File) (int, error) {
	content, err := ioutil.ReadAll(f)

	return len(content), err
}

func GetExt(fileName string) string {
	return path.Ext(fileName)
}

func CheckNotExist(src string) bool {
	_, err := os.Stat(src)

	return os.IsNotExist(err)
}

func CheckPermission(src string) bool {
	_, err := os.Stat(src)

	return os.IsPermission(err)
}

func IsNotExistMkDir(src string) error {
	if notExist := CheckNotExist(src); notExist == true {
		if err := MkDir(src); err != nil {
			return err
		}
	}

	return nil
}

func MkDir(src string) error {
	err := os.MkdirAll(src, os.ModePerm)
	if err != nil {
		return err
	}

	return nil
}

func Open(name string, flag int, perm os.FileMode) (*os.File, error) {
	f, err := os.OpenFile(name, flag, perm)
	if err != nil {
		return nil, err
	}

	return f, nil
}
```

在这里我们一共封装了 7 个 方法

- GetSize：获取文件大小
- GetExt：获取文件后缀
- CheckNotExist：检查文件是否存在
- CheckPermission：检查文件权限
- IsNotExistMkDir：如果不存在则新建文件夹
- MkDir：新建文件夹
- Open：打开文件

在这里我们用到了 `mime/multipart` 包，它主要实现了 MIME 的 multipart 解析，主要适用于 [HTTP](https://tools.ietf.org/html/rfc2388) 和常见浏览器生成的 multipart 主体

multipart 又是什么，[rfc2388](https://tools.ietf.org/html/rfc2388) 的 multipart/form-data 了解一下

### 第二步

我们在第一步已经将 file 重新封装了一层，在这一步我们将原先 logging 包的方法都修改掉

1、打开 pkg/logging/file.go 文件，修改文件内容：

```go
package logging

import (
	"fmt"
	"os"
	"time"

	"github.com/EDDYCJY/go-gin-example/pkg/setting"
	"github.com/EDDYCJY/go-gin-example/pkg/file"
)

func getLogFilePath() string {
	return fmt.Sprintf("%s%s", setting.AppSetting.RuntimeRootPath, setting.AppSetting.LogSavePath)
}

func getLogFileName() string {
	return fmt.Sprintf("%s%s.%s",
		setting.AppSetting.LogSaveName,
		time.Now().Format(setting.AppSetting.TimeFormat),
		setting.AppSetting.LogFileExt,
	)
}

func openLogFile(fileName, filePath string) (*os.File, error) {
	dir, err := os.Getwd()
	if err != nil {
		return nil, fmt.Errorf("os.Getwd err: %v", err)
	}

	src := dir + "/" + filePath
	perm := file.CheckPermission(src)
	if perm == true {
		return nil, fmt.Errorf("file.CheckPermission Permission denied src: %s", src)
	}

	err = file.IsNotExistMkDir(src)
	if err != nil {
		return nil, fmt.Errorf("file.IsNotExistMkDir src: %s, err: %v", src, err)
	}

	f, err := file.Open(src + fileName, os.O_APPEND|os.O_CREATE|os.O_WRONLY, 0644)
	if err != nil {
		return nil, fmt.Errorf("Fail to OpenFile :%v", err)
	}

	return f, nil
}
```

我们将引用都改为了 file/file.go 包里的方法

2、打开 pkg/logging/log.go 文件，修改文件内容:

```go
package logging

...

func Setup() {
	var err error
	filePath := getLogFilePath()
	fileName := getLogFileName()
	F, err = openLogFile(fileName, filePath)
	if err != nil {
		log.Fatalln(err)
	}

	logger = log.New(F, DefaultPrefix, log.LstdFlags)
}

...
```

由于原方法形参改变了，因此 openLogFile 也需要调整

## 实现上传图片接口

这一小节，我们开始实现上次图片相关的一些方法和功能

首先需要在 blog_article 中增加字段 `cover_image_url`，格式为 `varchar(255) DEFAULT '' COMMENT '封面图片地址'`

### 第零步

一般不会直接将上传的图片名暴露出来，因此我们对图片名进行 MD5 来达到这个效果

在 util 目录下新建 md5.go，写入文件内容：

```go
package util

import (
	"crypto/md5"
	"encoding/hex"
)

func EncodeMD5(value string) string {
	m := md5.New()
	m.Write([]byte(value))

	return hex.EncodeToString(m.Sum(nil))
}

```

### 第一步

在先前我们已经把底层方法给封装好了，实质这一步为封装 image 的处理逻辑

在 pkg 目录下新建 upload/image.go 文件，写入文件内容：

```go
package upload

import (
	"os"
	"path"
	"log"
	"fmt"
	"strings"
	"mime/multipart"

	"github.com/EDDYCJY/go-gin-example/pkg/file"
	"github.com/EDDYCJY/go-gin-example/pkg/setting"
	"github.com/EDDYCJY/go-gin-example/pkg/logging"
	"github.com/EDDYCJY/go-gin-example/pkg/util"
)

func GetImageFullUrl(name string) string {
	return setting.AppSetting.ImagePrefixUrl + "/" + GetImagePath() + name
}

func GetImageName(name string) string {
	ext := path.Ext(name)
	fileName := strings.TrimSuffix(name, ext)
	fileName = util.EncodeMD5(fileName)

	return fileName + ext
}

func GetImagePath() string {
	return setting.AppSetting.ImageSavePath
}

func GetImageFullPath() string {
	return setting.AppSetting.RuntimeRootPath + GetImagePath()
}

func CheckImageExt(fileName string) bool {
	ext := file.GetExt(fileName)
	for _, allowExt := range setting.AppSetting.ImageAllowExts {
		if strings.ToUpper(allowExt) == strings.ToUpper(ext) {
			return true
		}
	}

	return false
}

func CheckImageSize(f multipart.File) bool {
	size, err := file.GetSize(f)
	if err != nil {
		log.Println(err)
		logging.Warn(err)
		return false
	}

	return size <= setting.AppSetting.ImageMaxSize
}

func CheckImage(src string) error {
	dir, err := os.Getwd()
	if err != nil {
		return fmt.Errorf("os.Getwd err: %v", err)
	}

	err = file.IsNotExistMkDir(dir + "/" + src)
	if err != nil {
		return fmt.Errorf("file.IsNotExistMkDir err: %v", err)
	}

	perm := file.CheckPermission(src)
	if perm == true {
		return fmt.Errorf("file.CheckPermission Permission denied src: %s", src)
	}

	return nil
}
```

在这里我们实现了 7 个方法，如下：

- GetImageFullUrl：获取图片完整访问 URL
- GetImageName：获取图片名称
- GetImagePath：获取图片路径
- GetImageFullPath：获取图片完整路径
- CheckImageExt：检查图片后缀
- CheckImageSize：检查图片大小
- CheckImage：检查图片

这里基本是对底层代码的二次封装，为了更灵活的处理一些图片特有的逻辑，并且方便修改，不直接对外暴露下层

### 第二步

这一步将编写上传图片的业务逻辑，在 routers/api 目录下 新建 upload.go 文件，写入文件内容:

```go
package api

import (
	"net/http"

	"github.com/gin-gonic/gin"

	"github.com/EDDYCJY/go-gin-example/pkg/e"
	"github.com/EDDYCJY/go-gin-example/pkg/logging"
	"github.com/EDDYCJY/go-gin-example/pkg/upload"
)

func UploadImage(c *gin.Context) {
	code := e.SUCCESS
	data := make(map[string]string)

	file, image, err := c.Request.FormFile("image")
	if err != nil {
		logging.Warn(err)
		code = e.ERROR
		c.JSON(http.StatusOK, gin.H{
			"code": code,
			"msg":  e.GetMsg(code),
			"data": data,
		})
	}

	if image == nil {
		code = e.INVALID_PARAMS
	} else {
		imageName := upload.GetImageName(image.Filename)
		fullPath := upload.GetImageFullPath()
		savePath := upload.GetImagePath()

		src := fullPath + imageName
		if ! upload.CheckImageExt(imageName) || ! upload.CheckImageSize(file) {
			code = e.ERROR_UPLOAD_CHECK_IMAGE_FORMAT
		} else {
			err := upload.CheckImage(fullPath)
			if err != nil {
				logging.Warn(err)
				code = e.ERROR_UPLOAD_CHECK_IMAGE_FAIL
			} else if err := c.SaveUploadedFile(image, src); err != nil {
				logging.Warn(err)
				code = e.ERROR_UPLOAD_SAVE_IMAGE_FAIL
			} else {
				data["image_url"] = upload.GetImageFullUrl(imageName)
				data["image_save_url"] = savePath + imageName
			}
		}
	}

	c.JSON(http.StatusOK, gin.H{
		"code": code,
		"msg":  e.GetMsg(code),
		"data": data,
	})
}
```

所涉及的错误码（需在 pkg/e/code.go、msg.go 添加）：

```go
// 保存图片失败
ERROR_UPLOAD_SAVE_IMAGE_FAIL = 30001
// 检查图片失败
ERROR_UPLOAD_CHECK_IMAGE_FAIL = 30002
// 校验图片错误，图片格式或大小有问题
ERROR_UPLOAD_CHECK_IMAGE_FORMAT = 30003
```

在这一大段的业务逻辑中，我们做了如下事情：

- c.Request.FormFile：获取上传的图片（返回提供的表单键的第一个文件）
- CheckImageExt、CheckImageSize 检查图片大小，检查图片后缀
- CheckImage：检查上传图片所需（权限、文件夹）
- SaveUploadedFile：保存图片

总的来说，就是 入参 -> 检查 -》 保存 的应用流程

### 第三步

打开 routers/router.go 文件，增加路由 `r.POST("/upload", api.UploadImage)` ，如：

```go
func InitRouter() *gin.Engine {
	r := gin.New()
    ...
	r.GET("/auth", api.GetAuth)
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.POST("/upload", api.UploadImage)

	apiv1 := r.Group("/api/v1")
	apiv1.Use(jwt.JWT())
	{
		...
	}

	return r
}
```

### 验证

最后我们请求一下上传图片的接口，测试所编写的功能

![image](https://s2.ax1x.com/2020/02/15/1xumb8.jpg)

检查目录下是否含文件（注意权限问题）

```
$ pwd
$GOPATH/src/github.com/EDDYCJY/go-gin-example/runtime/upload/images

$ ll
... 96a3be3cf272e017046d1b2674a52bd3.jpg
... c39fa784216313cf2faa7c98739fc367.jpeg
```

在这里我们一共返回了 2 个参数，一个是完整的访问 URL，另一个为保存路径

## 实现 http.FileServer

在完成了上一小节后，我们还需要让前端能够访问到图片，一般是如下：

- CDN
- http.FileSystem

在公司的话，CDN 或自建分布式文件系统居多，也不需要过多关注。而在实践里的话肯定是本地搭建了，Go 本身对此就有很好的支持，而 Gin 更是再封装了一层，只需要在路由增加一行代码即可

### r.StaticFS

打开 routers/router.go 文件，增加路由 `r.StaticFS("/upload/images", http.Dir(upload.GetImageFullPath()))`，如：

```go
func InitRouter() *gin.Engine {
    ...
	r.StaticFS("/upload/images", http.Dir(upload.GetImageFullPath()))

	r.GET("/auth", api.GetAuth)
	r.GET("/swagger/*any", ginSwagger.WrapHandler(swaggerFiles.Handler))
	r.POST("/upload", api.UploadImage)
    ...
}
```

### 它做了什么

当访问 $HOST/upload/images 时，将会读取到 $GOPATH/src/github.com/EDDYCJY/go-gin-example/runtime/upload/images 下的文件

而这行代码又做了什么事呢，我们来看看方法原型

```go
// StaticFS works just like `Static()` but a custom `http.FileSystem` can be used instead.
// Gin by default user: gin.Dir()
func (group *RouterGroup) StaticFS(relativePath string, fs http.FileSystem) IRoutes {
	if strings.Contains(relativePath, ":") || strings.Contains(relativePath, "*") {
		panic("URL parameters can not be used when serving a static folder")
	}
	handler := group.createStaticHandler(relativePath, fs)
	urlPattern := path.Join(relativePath, "/*filepath")

	// Register GET and HEAD handlers
	group.GET(urlPattern, handler)
	group.HEAD(urlPattern, handler)
	return group.returnObj()
}
```

首先在暴露的 URL 中禁止了 \* 和 : 符号的使用，通过 `createStaticHandler` 创建了静态文件服务，实质最终调用的还是 `fileServer.ServeHTTP` 和一些处理逻辑了

```go
func (group *RouterGroup) createStaticHandler(relativePath string, fs http.FileSystem) HandlerFunc {
	absolutePath := group.calculateAbsolutePath(relativePath)
	fileServer := http.StripPrefix(absolutePath, http.FileServer(fs))
	_, nolisting := fs.(*onlyfilesFS)
	return func(c *Context) {
		if nolisting {
			c.Writer.WriteHeader(404)
		}
		fileServer.ServeHTTP(c.Writer, c.Request)
	}
}
```

#### http.StripPrefix

我们可以留意下 `fileServer := http.StripPrefix(absolutePath, http.FileServer(fs))` 这段语句，在静态文件服务中很常见，它有什么作用呢？

`http.StripPrefix` 主要作用是从请求 URL 的路径中删除给定的前缀，最终返回一个 `Handler`

通常 http.FileServer 要与 http.StripPrefix 相结合使用，否则当你运行：

```go
http.Handle("/upload/images", http.FileServer(http.Dir("upload/images")))
```

会无法正确的访问到文件目录，因为 `/upload/images` 也包含在了 URL 路径中，必须使用：

```go
http.Handle("/upload/images", http.StripPrefix("upload/images", http.FileServer(http.Dir("upload/images"))))
```

#### /\*filepath

到下面可以看到 `urlPattern := path.Join(relativePath, "/*filepath")`，`/*filepath` 你是谁，你在这里有什么用，你是 Gin 的产物吗?

通过语义可得知是路由的处理逻辑，而 Gin 的路由是基于 httprouter 的，通过查阅文档可得到以下信息

```
Pattern: /src/*filepath

 /src/                     match
 /src/somefile.go          match
 /src/subdir/somefile.go   match
```

`*filepath` 将匹配所有文件路径，并且 `*filepath` 必须在 Pattern 的最后

### 验证

重新执行 `go run main.go` ，去访问刚刚在 upload 接口得到的图片地址，检查 http.FileSystem 是否正常

![image](https://s2.ax1x.com/2020/02/15/1xu4Gd.jpg)

## 修改文章接口

接下来，需要你修改 routers/api/v1/article.go 的 AddArticle、EditArticle 两个接口

- 新增、更新文章接口：支持入参 cover_image_url
- 新增、更新文章接口：增加对 cover_image_url 的非空、最长长度校验

这块前面文章讲过，如果有问题可以参考项目的代码 👌

## 总结

在这章节中，我们简单的分析了下需求，对应用做出了一个小规划并实施

完成了清单中的功能点和优化，在实际项目中也是常见的场景，希望你能够细细品尝并针对一些点进行深入学习

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 02 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-06-02-application-redis.md
================================================
---

title:      "「连载十三」优化你的应用结构和实现Redis缓存"
date:       2018-06-02 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 前言

之前就在想，不少教程或示例的代码设计都是一步到位的（也没问题）

但实际操作的读者真的能够理解透彻为什么吗？左思右想，有了今天这一章的内容，我认为实际经历过一遍印象会更加深刻

## 本文目标

在本章节，将介绍以下功能的整理：

- 抽离、分层业务逻辑：减轻 routers.go 内的 api 方法的逻辑（但本文暂不分层 repository，这块逻辑还不重）。
- 增加容错性：对 gorm 的错误进行判断。
- Redis 缓存：对获取数据类的接口增加缓存设置。
- 减少重复冗余代码。

## 问题在哪？

在规划阶段我们发现了一个问题，这是目前的伪代码：

```go
if ! HasErrors() {
	if ExistArticleByID(id) {
		DeleteArticle(id)
		code = e.SUCCESS
	} else {
		code = e.ERROR_NOT_EXIST_ARTICLE
	}
} else {
	for _, err := range valid.Errors {
		logging.Info(err.Key, err.Message)
	}
}

c.JSON(http.StatusOK, gin.H{
	"code": code,
	"msg":  e.GetMsg(code),
	"data": make(map[string]string),
})
```

如果加上规划内的功能逻辑呢，伪代码会变成：

```go
if ! HasErrors() {
    exists, err := ExistArticleByID(id)
    if err == nil {
        if exists {
    		err = DeleteArticle(id)
    		if err == nil {
    		    code = e.SUCCESS
    		} else {
    		    code = e.ERROR_XXX
    		}
    	} else {
    		code = e.ERROR_NOT_EXIST_ARTICLE
    	}
    } else {
        code = e.ERROR_XXX
    }
} else {
	for _, err := range valid.Errors {
		logging.Info(err.Key, err.Message)
	}
}

c.JSON(http.StatusOK, gin.H{
	"code": code,
	"msg":  e.GetMsg(code),
	"data": make(map[string]string),
})
```

如果缓存的逻辑也加进来，后面慢慢不断的迭代，岂不是会变成如下图一样？

![image](https://coolshell.cn/wp-content/uploads/2017/04/IMG_7411.jpg)

现在我们发现了问题，应及时解决这个代码结构问题，同时把代码写的清晰、漂亮、易读易改也是一个重要指标

## 如何改？

在左耳朵耗子的文章中，这类代码被称为 “箭头型” 代码，有如下几个问题：

1、我的显示器不够宽，箭头型代码缩进太狠了，需要我来回拉水平滚动条，这让我在读代码的时候，相当的不舒服

2、除了宽度外还有长度，有的代码的 if-else 里的 if-else 里的 if-else 的代码太多，读到中间你都不知道中间的代码是经过了什么样的层层检查才来到这里的

总而言之，“箭头型代码”如果嵌套太多，代码太长的话，会相当容易让维护代码的人（包括自己）迷失在代码中，因为看到最内层的代码时，你已经不知道前面的那一层一层的条件判断是什么样的，代码是怎么运行到这里的，所以，箭头型代码是非常难以维护和 Debug 的。

简单的来说，就是**让出错的代码先返回，前面把所有的错误判断全判断掉，然后就剩下的就是正常的代码了**

（注意：本段引用自耗子哥的 [如何重构“箭头型”代码](https://coolshell.cn/articles/17757.html)，建议细细品尝）

## 落实

本项目将对既有代码进行优化和实现缓存，希望你习得方法并对其他地方也进行优化

第一步：完成 Redis 的基础设施建设（需要你先装好 Redis）

第二步：对现有代码进行拆解、分层（不会贴上具体步骤的代码，希望你能够实操一波，加深理解 🤔）

### Redis

#### 一、配置

打开 conf/app.ini 文件，新增配置：

```ini
...
[redis]
Host = 127.0.0.1:6379
Password =
MaxIdle = 30
MaxActive = 30
IdleTimeout = 200
```

#### 二、缓存 Prefix

打开 pkg/e 目录，新建 cache.go，写入内容：

```go
package e

const (
	CACHE_ARTICLE = "ARTICLE"
	CACHE_TAG     = "TAG"
)
```

#### 三、缓存 Key

（1）、打开 service 目录，新建 cache_service/article.go

写入内容：[传送门](https://github.com/EDDYCJY/go-gin-example/blob/master/service/cache_service/article.go)

（2）、打开 service 目录，新建 cache_service/tag.go

写入内容：[传送门](https://github.com/EDDYCJY/go-gin-example/blob/master/service/cache_service/tag.go)

这一部分主要是编写获取缓存 KEY 的方法，直接参考传送门即可

#### 四、Redis 工具包

打开 pkg 目录，新建 gredis/redis.go，写入内容：

```go
package gredis

import (
	"encoding/json"
	"time"

	"github.com/gomodule/redigo/redis"

	"github.com/EDDYCJY/go-gin-example/pkg/setting"
)

var RedisConn *redis.Pool

func Setup() error {
	RedisConn = &redis.Pool{
		MaxIdle:     setting.RedisSetting.MaxIdle,
		MaxActive:   setting.RedisSetting.MaxActive,
		IdleTimeout: setting.RedisSetting.IdleTimeout,
		Dial: func() (redis.Conn, error) {
			c, err := redis.Dial("tcp", setting.RedisSetting.Host)
			if err != nil {
				return nil, err
			}
			if setting.RedisSetting.Password != "" {
				if _, err := c.Do("AUTH", setting.RedisSetting.Password); err != nil {
					c.Close()
					return nil, err
				}
			}
			return c, err
		},
		TestOnBorrow: func(c redis.Conn, t time.Time) error {
			_, err := c.Do("PING")
			return err
		},
	}

	return nil
}

func Set(key string, data interface{}, time int) error {
	conn := RedisConn.Get()
	defer conn.Close()

	value, err := json.Marshal(data)
	if err != nil {
		return err
	}

	_, err = conn.Do("SET", key, value)
	if err != nil {
		return err
	}

	_, err = conn.Do("EXPIRE", key, time)
	if err != nil {
		return err
	}

	return nil
}

func Exists(key string) bool {
	conn := RedisConn.Get()
	defer conn.Close()

	exists, err := redis.Bool(conn.Do("EXISTS", key))
	if err != nil {
		return false
	}

	return exists
}

func Get(key string) ([]byte, error) {
	conn := RedisConn.Get()
	defer conn.Close()

	reply, err := redis.Bytes(conn.Do("GET", key))
	if err != nil {
		return nil, err
	}

	return reply, nil
}

func Delete(key string) (bool, error) {
	conn := RedisConn.Get()
	defer conn.Close()

	return redis.Bool(conn.Do("DEL", key))
}

func LikeDeletes(key string) error {
	conn := RedisConn.Get()
	defer conn.Close()

	keys, err := redis.Strings(conn.Do("KEYS", "*"+key+"*"))
	if err != nil {
		return err
	}

	for _, key := range keys {
		_, err = Delete(key)
		if err != nil {
			return err
		}
	}

	return nil
}
```

在这里我们做了一些基础功能封装

1、设置 RedisConn 为 redis.Pool（连接池）并配置了它的一些参数：

- Dial：提供创建和配置应用程序连接的一个函数

- TestOnBorrow：可选的应用程序检查健康功能

- MaxIdle：最大空闲连接数

- MaxActive：在给定时间内，允许分配的最大连接数（当为零时，没有限制）

- IdleTimeout：在给定时间内将会保持空闲状态，若到达时间限制则关闭连接（当为零时，没有限制）

2、封装基础方法

文件内包含 Set、Exists、Get、Delete、LikeDeletes 用于支撑目前的业务逻辑，而在里面涉及到了如方法：

（1）`RedisConn.Get()`：在连接池中获取一个活跃连接

（2）`conn.Do(commandName string, args ...interface{})`：向 Redis 服务器发送命令并返回收到的答复

（3）`redis.Bool(reply interface{}, err error)`：将命令返回转为布尔值

（4）`redis.Bytes(reply interface{}, err error)`：将命令返回转为 Bytes

（5）`redis.Strings(reply interface{}, err error)`：将命令返回转为 []string

在 [redigo](https://godoc.org/github.com/gomodule/redigo/redis) 中包含大量类似的方法，万变不离其宗，建议熟悉其使用规则和 [Redis 命令](http://doc.redisfans.com/index.html) 即可

到这里为止，Redis 就可以愉快的调用啦。另外受篇幅限制，这块的深入讲解会另外开设！

### 拆解、分层

在先前规划中，引出几个方法去优化我们的应用结构

- 错误提前返回
- 统一返回方法
- 抽离 Service，减轻 routers/api 的逻辑，进行分层
- 增加 gorm 错误判断，让错误提示更明确（增加内部错误码）

#### 编写返回方法

要让错误提前返回，c.JSON 的侵入是不可避免的，但是可以让其更具可变性，指不定哪天就变 XML 了呢？

1、打开 pkg 目录，新建 app/request.go，写入文件内容：

```go
package app

import (
	"github.com/astaxie/beego/validation"

	"github.com/EDDYCJY/go-gin-example/pkg/logging"
)

func MarkErrors(errors []*validation.Error) {
	for _, err := range errors {
		logging.Info(err.Key, err.Message)
	}

	return
}
```

2、打开 pkg 目录，新建 app/response.go，写入文件内容：

```go
package app

import (
	"github.com/gin-gonic/gin"

	"github.com/EDDYCJY/go-gin-example/pkg/e"
)

type Gin struct {
	C *gin.Context
}

func (g *Gin) Response(httpCode, errCode int, data interface{}) {
	g.C.JSON(httpCode, gin.H{
		"code": errCode,
		"msg":  e.GetMsg(errCode),
		"data": data,
	})

	return
}
```

这样子以后如果要变动，直接改动 app 包内的方法即可

#### 修改既有逻辑

打开 routers/api/v1/article.go，查看修改 GetArticle 方法后的代码为：

```go
func GetArticle(c *gin.Context) {
	appG := app.Gin{c}
	id := com.StrTo(c.Param("id")).MustInt()
	valid := validation.Validation{}
	valid.Min(id, 1, "id").Message("ID必须大于0")

	if valid.HasErrors() {
		app.MarkErrors(valid.Errors)
		appG.Response(http.StatusOK, e.INVALID_PARAMS, nil)
		return
	}

	articleService := article_service.Article{ID: id}
	exists, err := articleService.ExistByID()
	if err != nil {
		appG.Response(http.StatusOK, e.ERROR_CHECK_EXIST_ARTICLE_FAIL, nil)
		return
	}
	if !exists {
		appG.Response(http.StatusOK, e.ERROR_NOT_EXIST_ARTICLE, nil)
		return
	}

	article, err := articleService.Get()
	if err != nil {
		appG.Response(http.StatusOK, e.ERROR_GET_ARTICLE_FAIL, nil)
		return
	}

	appG.Response(http.StatusOK, e.SUCCESS, article)
}
```

这里有几个值得变动点，主要是在内部增加了错误返回，如果存在错误则直接返回。另外进行了分层，业务逻辑内聚到了 service 层中去，而 routers/api（controller）显著减轻，代码会更加的直观

例如 service/article_service 下的 `articleService.Get()` 方法：

```go
func (a *Article) Get() (*models.Article, error) {
	var cacheArticle *models.Article

	cache := cache_service.Article{ID: a.ID}
	key := cache.GetArticleKey()
	if gredis.Exists(key) {
		data, err := gredis.Get(key)
		if err != nil {
			logging.Info(err)
		} else {
			json.Unmarshal(data, &cacheArticle)
			return cacheArticle, nil
		}
	}

	article, err := models.GetArticle(a.ID)
	if err != nil {
		return nil, err
	}

	gredis.Set(key, article, 3600)
	return article, nil
}
```

而对于 gorm 的 错误返回设置，只需要修改 models/article.go 如下:

```go
func GetArticle(id int) (*Article, error) {
	var article Article
	err := db.Where("id = ? AND deleted_on = ? ", id, 0).First(&article).Related(&article.Tag).Error
	if err != nil && err != gorm.ErrRecordNotFound {
		return nil, err
	}

	return &article, nil
}
```

习惯性增加 .Error，把控绝大部分的错误。另外需要注意一点，在 gorm 中，查找不到记录也算一种 “错误” 哦

## 最后

显然，本章节并不是你跟着我敲系列。我给你的课题是 “实现 Redis 缓存并优化既有的业务逻辑代码”

让其能够不断地适应业务的发展，让代码更清晰易读，且呈层级和结构性

如果有疑惑，可以到 [go-gin-example](https://github.com/EDDYCJY/go-gin-example) 看看我是怎么写的，你是怎么写的，又分别有什么优势、劣势，取长补短一波？

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

### 推荐阅读

- [如何重构“箭头型”代码](https://coolshell.cn/articles/17757.html)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-06-14-excel.md
================================================
---

title:      "「连载十四」实现导出、导入 Excel"
date:       2018-06-14 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 导出功能的实现

## 本文目标

在本节，我们将实现对标签信息的导出、导入功能，这是很标配功能了，希望你掌握基础的使用方式。

另外在本文我们使用了 2 个 Excel 的包，excelize 最初的 XML 格式文件的一些结构，是通过 tealeg/xlsx 格式文件结构演化而来的，因此特意在此都展示了，你可以根据自己的场景和喜爱去使用。

## 配置

首先要指定导出的 Excel 文件的存储路径，在 app.ini 中增加配置：

```ini
[app]
...

ExportSavePath = export/
```

修改 setting.go 的 App struct：

```go
type App struct {
	JwtSecret       string
	PageSize        int
	PrefixUrl       string

	RuntimeRootPath string

	ImageSavePath  string
	ImageMaxSize   int
	ImageAllowExts []string

	ExportSavePath string

	LogSavePath string
	LogSaveName string
	LogFileExt  string
	TimeFormat  string
}
```

在这里需增加 ExportSavePath 配置项，另外将先前 ImagePrefixUrl 改为 PrefixUrl 用于支撑两者的 HOST 获取

（注意修改 image.go 的 GetImageFullUrl 方法）

## pkg

新建 pkg/export/excel.go 文件，如下：

```go
package export

import "github.com/EDDYCJY/go-gin-example/pkg/setting"

func GetExcelFullUrl(name string) string {
	return setting.AppSetting.PrefixUrl + "/" + GetExcelPath() + name
}

func GetExcelPath() string {
	return setting.AppSetting.ExportSavePath
}

func GetExcelFullPath() string {
	return setting.AppSetting.RuntimeRootPath + GetExcelPath()
}
```

这里编写了一些常用的方法，以后取值方式如果有变动，直接改内部代码即可，对外不可见

## 尝试一下标准库

```go
f, err := os.Create(export.GetExcelFullPath() + "test.csv")
if err != nil {
	panic(err)
}
defer f.Close()

f.WriteString("\xEF\xBB\xBF")

w := csv.NewWriter(f)
data := [][]string{
	{"1", "test1", "test1-1"},
	{"2", "test2", "test2-1"},
	{"3", "test3", "test3-1"},
}

w.WriteAll(data)
```

在 Go 提供的标准库 encoding/csv 中，天然的支持 csv 文件的读取和处理，在本段代码中，做了如下工作：

1、os.Create：

创建了一个 test.csv 文件

2、f.WriteString("\xEF\xBB\xBF")：

`\xEF\xBB\xBF` 是 UTF-8 BOM 的 16 进制格式，在这里的用处是标识文件的编码格式，通常会出现在文件的开头，因此第一步就要将其写入。如果不标识 UTF-8 的编码格式的话，写入的汉字会显示为乱码

3、csv.NewWriter：

```go
func NewWriter(w io.Writer) *Writer {
	return &Writer{
		Comma: ',',
		w:     bufio.NewWriter(w),
	}
}
```

4、w.WriteAll：

```go
func (w *Writer) WriteAll(records [][]string) error {
	for _, record := range records {
		err := w.Write(record)
		if err != nil {
			return err
		}
	}
	return w.w.Flush()
}
```

WriteAll 实际是对 Write 的封装，需要注意在最后调用了 `w.w.Flush()`，这充分了说明了 WriteAll 的使用场景，你可以想想作者的设计用意

## 导出

### Service 方法

打开 service/tag.go，增加 Export 方法，如下：

```go
func (t *Tag) Export() (string, error) {
	tags, err := t.GetAll()
	if err != nil {
		return "", err
	}

	file := xlsx.NewFile()
	sheet, err := file.AddSheet("标签信息")
	if err != nil {
		return "", err
	}

	titles := []string{"ID", "名称", "创建人", "创建时间", "修改人", "修改时间"}
	row := sheet.AddRow()

	var cell *xlsx.Cell
	for _, title := range titles {
		cell = row.AddCell()
		cell.Value = title
	}

	for _, v := range tags {
		values := []string{
			strconv.Itoa(v.ID),
			v.Name,
			v.CreatedBy,
			strconv.Itoa(v.CreatedOn),
			v.ModifiedBy,
			strconv.Itoa(v.ModifiedOn),
		}

		row = sheet.AddRow()
		for _, value := range values {
			cell = row.AddCell()
			cell.Value = value
		}
	}

	time := strconv.Itoa(int(time.Now().Unix()))
	filename := "tags-" + time + ".xlsx"

	fullPath := export.GetExcelFullPath() + filename
	err = file.Save(fullPath)
	if err != nil {
		return "", err
	}

	return filename, nil
}
```

## routers 入口

打开 routers/api/v1/tag.go，增加如下方法：

```go
func ExportTag(c *gin.Context) {
	appG := app.Gin{C: c}
	name := c.PostForm("name")
	state := -1
	if arg := c.PostForm("state"); arg != "" {
		state = com.StrTo(arg).MustInt()
	}

	tagService := tag_service.Tag{
		Name:  name,
		State: state,
	}

	filename, err := tagService.Export()
	if err != nil {
		appG.Response(http.StatusOK, e.ERROR_EXPORT_TAG_FAIL, nil)
		return
	}

	appG.Response(http.StatusOK, e.SUCCESS, map[string]string{
		"export_url":      export.GetExcelFullUrl(filename),
		"export_save_url": export.GetExcelPath() + filename,
	})
}
```

### 路由

在 routers/router.go 文件中增加路由方法，如下

```go
apiv1 := r.Group("/api/v1")
apiv1.Use(jwt.JWT())
{
	...
	//导出标签
	r.POST("/tags/export", v1.ExportTag)
}
```

### 验证接口

访问 `http://127.0.0.1:8000/tags/export`，结果如下：

```json
{
  "code": 200,
  "data": {
    "export_save_url": "export/tags-1528903393.xlsx",
    "export_url": "http://127.0.0.1:8000/export/tags-1528903393.xlsx"
  },
  "msg": "ok"
}
```

最终通过接口返回了导出文件的地址和保存地址

### StaticFS

那你想想，现在直接访问地址肯定是无法下载文件的，那么该如何做呢？

打开 router.go 文件，增加代码如下：

```go
r.StaticFS("/export", http.Dir(export.GetExcelFullPath()))
```

若你不理解，强烈建议温习下前面的章节，举一反三

## 验证下载

再次访问上面的 export_url ，如：`http://127.0.0.1:8000/export/tags-1528903393.xlsx`，是不是成功了呢？

## 导入

### Service 方法

打开 service/tag.go，增加 Import 方法，如下：

```go
func (t *Tag) Import(r io.Reader) error {
	xlsx, err := excelize.OpenReader(r)
	if err != nil {
		return err
	}

	rows := xlsx.GetRows("标签信息")
	for irow, row := range rows {
		if irow > 0 {
			var data []string
			for _, cell := range row {
				data = append(data, cell)
			}

			models.AddTag(data[1], 1, data[2])
		}
	}

	return nil
}
```

## routers 入口

打开 routers/api/v1/tag.go，增加如下方法：

```go
func ImportTag(c *gin.Context) {
	appG := app.Gin{C: c}

	file, _, err := c.Request.FormFile("file")
	if err != nil {
		logging.Warn(err)
		appG.Response(http.StatusOK, e.ERROR, nil)
		return
	}

	tagService := tag_service.Tag{}
	err = tagService.Import(file)
	if err != nil {
		logging.Warn(err)
		appG.Response(http.StatusOK, e.ERROR_IMPORT_TAG_FAIL, nil)
		return
	}

	appG.Response(http.StatusOK, e.SUCCESS, nil)
}
```

### 路由

在 routers/router.go 文件中增加路由方法，如下

```go
apiv1 := r.Group("/api/v1")
apiv1.Use(jwt.JWT())
{
	...
	//导入标签
	r.POST("/tags/import", v1.ImportTag)
}
```

### 验证

![image](https://s2.ax1x.com/2020/02/15/1xKtSA.jpg)

在这里我们将先前导出的 Excel 文件作为入参，访问 `http://127.0.0.01:8000/tags/import`，检查返回和数据是否正确入库

## 总结

在本文中，简单介绍了 Excel 的导入、导出的使用方式，使用了以下 2 个包：

- [tealeg/xlsx](https://github.com/tealeg/xlsx)
- [360EntSecGroup-Skylar/excelize](https://github.com/360EntSecGroup-Skylar/excelize)

你可以细细阅读一下它的实现和使用方式，对你的把控更有帮助 🤔

## 课外

- tag：导出使用 excelize 的方式去实现（可能你会发现更简单哦）
- tag：导入去重功能实现
- artice ：导入、导出功能实现

也不失为你很好的练手机会，如果有兴趣，可以试试

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 02 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)



================================================
FILE: content/posts/go/gin/2018-07-05-image.md
================================================
---

title:      "「连载十五」生成二维码、合并海报"
date:       2018-07-05 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 图片生成
- 二维码生成

## 本文目标

在文章的详情页中，我们常常会需要去宣传它，而目前最常见的就是发海报了，今天我们将实现如下功能：

- 生成二维码

- 合并海报（背景图 + 二维码）

## 实现

首先，你需要在 App 配置项中增加二维码及其海报的存储路径，我们约定配置项名称为 `QrCodeSavePath`，值为 `qrcode/`，经过多节连载的你应该能够完成，若有不懂可参照 [go-gin-example](https://github.com/EDDYCJY/go-gin-example/blob/master/conf/app.ini#L14)。

## 生成二维码

### 安装

```
$ go get -u github.com/boombuler/barcode
```

### 工具包

考虑生成二维码这一动作贴合工具包的定义，且有公用的可能性，新建 pkg/qrcode/qrcode.go 文件，写入内容：

```go
package qrcode

import (
	"image/jpeg"

	"github.com/boombuler/barcode"
	"github.com/boombuler/barcode/qr"

	"github.com/EDDYCJY/go-gin-example/pkg/file"
	"github.com/EDDYCJY/go-gin-example/pkg/setting"
	"github.com/EDDYCJY/go-gin-example/pkg/util"
)

type QrCode struct {
	URL    string
	Width  int
	Height int
	Ext    string
	Level  qr.ErrorCorrectionLevel
	Mode   qr.Encoding
}

const (
	EXT_JPG = ".jpg"
)

func NewQrCode(url string, width, height int, level qr.ErrorCorrectionLevel, mode qr.Encoding) *QrCode {
	return &QrCode{
		URL:    url,
		Width:  width,
		Height: height,
		Level:  level,
		Mode:   mode,
		Ext:    EXT_JPG,
	}
}

func GetQrCodePath() string {
	return setting.AppSetting.QrCodeSavePath
}

func GetQrCodeFullPath() string {
	return setting.AppSetting.RuntimeRootPath + setting.AppSetting.QrCodeSavePath
}

func GetQrCodeFullUrl(name string) string {
	return setting.AppSetting.PrefixUrl + "/" + GetQrCodePath() + name
}

func GetQrCodeFileName(value string) string {
	return util.EncodeMD5(value)
}

func (q *QrCode) GetQrCodeExt() string {
	return q.Ext
}

func (q *QrCode) CheckEncode(path string) bool {
	src := path + GetQrCodeFileName(q.URL) + q.GetQrCodeExt()
	if file.CheckNotExist(src) == true {
		return false
	}

	return true
}

func (q *QrCode) Encode(path string) (string, string, error) {
	name := GetQrCodeFileName(q.URL) + q.GetQrCodeExt()
	src := path + name
	if file.CheckNotExist(src) == true {
		code, err := qr.Encode(q.URL, q.Level, q.Mode)
		if err != nil {
			return "", "", err
		}

		code, err = barcode.Scale(code, q.Width, q.Height)
		if err != nil {
			return "", "", err
		}

		f, err := file.MustOpen(name, path)
		if err != nil {
			return "", "", err
		}
		defer f.Close()

		err = jpeg.Encode(f, code, nil)
		if err != nil {
			return "", "", err
		}
	}

	return name, path, nil
}
```

这里主要聚焦 `func (q *QrCode) Encode` 方法，做了如下事情：

- 获取二维码生成路径
- 创建二维码
- 缩放二维码到指定大小
- 新建存放二维码图片的文件
- 将图像（二维码）以 JPEG 4：2：0 基线格式写入文件

另外在 `jpeg.Encode(f, code, nil)` 中，第三个参数可设置其图像质量，默认值为 75

```go
// DefaultQuality is the default quality encoding parameter.
const DefaultQuality = 75

// Options are the encoding parameters.
// Quality ranges from 1 to 100 inclusive, higher is better.
type Options struct {
	Quality int
}
```

### 路由方法

1、第一步

在 routers/api/v1/article.go 新增 GenerateArticlePoster 方法用于接口开发

2、第二步

在 routers/router.go 的 apiv1 中新增 `apiv1.POST("/articles/poster/generate", v1.GenerateArticlePoster)` 路由

3、第三步

修改 GenerateArticlePoster 方法，编写对应的生成逻辑，如下：

```go
const (
	QRCODE_URL = "https://github.com/EDDYCJY/blog#gin%E7%B3%BB%E5%88%97%E7%9B%AE%E5%BD%95"
)

func GenerateArticlePoster(c *gin.Context) {
	appG := app.Gin{c}
	qrc := qrcode.NewQrCode(QRCODE_URL, 300, 300, qr.M, qr.Auto)
	path := qrcode.GetQrCodeFullPath()
	_, _, err := qrc.Encode(path)
	if err != nil {
		appG.Response(http.StatusOK, e.ERROR, nil)
		return
	}

	appG.Response(http.StatusOK, e.SUCCESS, nil)
}
```

### 验证

通过 POST 方法访问 `http://127.0.0.1:8000/api/v1/articles/poster/generate?token=$token`（注意 \$token）

![image](https://s2.ax1x.com/2020/02/15/1xQmb6.jpg)

通过检查两个点确定功能是否正常，如下：

1、访问结果是否 200

2、本地目录是否成功生成二维码图片

![image](https://s2.ax1x.com/2020/02/15/1xQCUU.jpg)

## 合并海报

在这一节，将实现二维码图片与背景图合并成新的一张图，可用于常见的宣传海报等业务场景

### 背景图

![image](https://s2.ax1x.com/2020/02/15/1xMXgs.jpg)

将背景图另存为 runtime/qrcode/bg.jpg（实际应用，可存在 OSS 或其他地方）

### service 方法

打开 service/article_service 目录，新建 article_poster.go 文件，写入内容：

```go
package article_service

import (
	"image"
	"image/draw"
	"image/jpeg"
	"os"

	"github.com/EDDYCJY/go-gin-example/pkg/file"
	"github.com/EDDYCJY/go-gin-example/pkg/qrcode"
)

type ArticlePoster struct {
	PosterName string
	*Article
	Qr *qrcode.QrCode
}

func NewArticlePoster(posterName string, article *Article, qr *qrcode.QrCode) *ArticlePoster {
	return &ArticlePoster{
		PosterName: posterName,
		Article:    article,
		Qr:         qr,
	}
}

func GetPosterFlag() string {
	return "poster"
}

func (a *ArticlePoster) CheckMergedImage(path string) bool {
	if file.CheckNotExist(path+a.PosterName) == true {
		return false
	}

	return true
}

func (a *ArticlePoster) OpenMergedImage(path string) (*os.File, error) {
	f, err := file.MustOpen(a.PosterName, path)
	if err != nil {
		return nil, err
	}

	return f, nil
}

type ArticlePosterBg struct {
	Name string
	*ArticlePoster
	*Rect
	*Pt
}

type Rect struct {
	Name string
	X0   int
	Y0   int
	X1   int
	Y1   int
}

type Pt struct {
	X int
	Y int
}

func NewArticlePosterBg(name string, ap *ArticlePoster, rect *Rect, pt *Pt) *ArticlePosterBg {
	return &ArticlePosterBg{
		Name:          name,
		ArticlePoster: ap,
		Rect:          rect,
		Pt:            pt,
	}
}

func (a *ArticlePosterBg) Generate() (string, string, error) {
	fullPath := qrcode.GetQrCodeFullPath()
	fileName, path, err := a.Qr.Encode(fullPath)
	if err != nil {
		return "", "", err
	}

	if !a.CheckMergedImage(path) {
		mergedF, err := a.OpenMergedImage(path)
		if err != nil {
			return "", "", err
		}
		defer mergedF.Close()

		bgF, err := file.MustOpen(a.Name, path)
		if err != nil {
			return "", "", err
		}
		defer bgF.Close()

		qrF, err := file.MustOpen(fileName, path)
		if err != nil {
			return "", "", err
		}
		defer qrF.Close()

		bgImage, err := jpeg.Decode(bgF)
		if err != nil {
			return "", "", err
		}
		qrImage, err := jpeg.Decode(qrF)
		if err != nil {
			return "", "", err
		}

		jpg := image.NewRGBA(image.Rect(a.Rect.X0, a.Rect.Y0, a.Rect.X1, a.Rect.Y1))

		draw.Draw(jpg, jpg.Bounds(), bgImage, bgImage.Bounds().Min, draw.Over)
		draw.Draw(jpg, jpg.Bounds(), qrImage, qrImage.Bounds().Min.Sub(image.Pt(a.Pt.X, a.Pt.Y)), draw.Over)

		jpeg.Encode(mergedF, jpg, nil)
	}

	return fileName, path, nil
}
```

这里重点留意 `func (a *ArticlePosterBg) Generate()` 方法，做了如下事情：

- 获取二维码存储路径
- 生成二维码图像
- 检查合并后图像（指的是存放合并后的海报）是否存在
- 若不存在，则生成待合并的图像 mergedF
- 打开事先存放的背景图 bgF
- 打开生成的二维码图像 qrF
- 解码 bgF 和 qrF 返回 image.Image
- 创建一个新的 RGBA 图像
- 在 RGBA 图像上绘制 背景图（bgF）
- 在已绘制背景图的 RGBA 图像上，在指定 Point 上绘制二维码图像（qrF）
- 将绘制好的 RGBA 图像以 JPEG 4：2：0 基线格式写入合并后的图像文件（mergedF）

### 错误码

新增 [错误码](https://github.com/EDDYCJY/go-gin-example/blob/master/pkg/e/code.go#L27)，[错误提示](https://github.com/EDDYCJY/go-gin-example/blob/master/pkg/e/msg.go#L25)

### 路由方法

打开 routers/api/v1/article.go 文件，修改 GenerateArticlePoster 方法，编写最终的业务逻辑（含生成二维码及合并海报），如下：

```go
const (
	QRCODE_URL = "https://github.com/EDDYCJY/blog#gin%E7%B3%BB%E5%88%97%E7%9B%AE%E5%BD%95"
)

func GenerateArticlePoster(c *gin.Context) {
	appG := app.Gin{c}
	article := &article_service.Article{}
	qr := qrcode.NewQrCode(QRCODE_URL, 300, 300, qr.M, qr.Auto) // 目前写死 gin 系列路径，可自行增加业务逻辑
	posterName := article_service.GetPosterFlag() + "-" + qrcode.GetQrCodeFileName(qr.URL) + qr.GetQrCodeExt()
	articlePoster := article_service.NewArticlePoster(posterName, article, qr)
	articlePosterBgService := article_service.NewArticlePosterBg(
		"bg.jpg",
		articlePoster,
		&article_service.Rect{
			X0: 0,
			Y0: 0,
			X1: 550,
			Y1: 700,
		},
		&article_service.Pt{
			X: 125,
			Y: 298,
		},
	)

	_, filePath, err := articlePosterBgService.Generate()
	if err != nil {
		appG.Response(http.StatusOK, e.ERROR_GEN_ARTICLE_POSTER_FAIL, nil)
		return
	}

	appG.Response(http.StatusOK, e.SUCCESS, map[string]string{
		"poster_url":      qrcode.GetQrCodeFullUrl(posterName),
		"poster_save_url": filePath + posterName,
	})
}
```

这块涉及到大量知识，强烈建议阅读下，如下：

- [image.Rect](https://golang.org/pkg/image/#Rect)
- [image.Pt](https://golang.org/pkg/image/#Pt)
- [image.NewRGBA](https://golang.org/pkg/image/#NewRGBA)
- [jpeg.Encode](https://golang.org/pkg/image/jpeg/#Encode)
- [jpeg.Decode](https://golang.org/pkg/image/jpeg/#Decode)
- [draw.Op](https://golang.org/pkg/image/draw/#Op)
- [draw.Draw](https://golang.org/pkg/image/draw/#Draw)
- [go-imagedraw-package](https://blog.golang.org/go-imagedraw-package)

其所涉及、关联的库都建议研究一下

### StaticFS

在 routers/router.go 文件，增加如下代码:

```go
r.StaticFS("/qrcode", http.Dir(qrcode.GetQrCodeFullPath()))
```

### 验证

![image](https://s2.ax1x.com/2020/02/15/1xMLCQ.jpg)

访问完整的 URL 路径，返回合成后的海报并扫除二维码成功则正确 🤓

![image](https://s2.ax1x.com/2020/02/15/1xMhjI.jpg)

## 总结

在本章节实现了两个很常见的业务功能，分别是生成二维码和合并海报。希望你能够仔细阅读我给出的链接，这块的知识量不少，想要用好图像处理的功能，必须理解对应的思路，举一反三

最后希望对你有所帮助 👌

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 02 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-07-07-font.md
================================================
---

title:      "「连载十六」在图片上绘制文字"
date:       2018-07-07 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
---

## 知识点

- 字体库使用
- 图片合成

## 本文目标

主要实现**合并后的海报上绘制文字**的功能（这个需求也是常见的很了），内容比较简单。

## 实现

这里使用的是 [微软雅黑](https://github.com/EDDYCJY/go-gin-example/blob/master/runtime/fonts/msyhbd.ttc) 的字体，请点击进行下载并**存放到 runtime/fonts 目录**下（字体文件占 16 MB 大小）

### 安装

```
$ go get -u github.com/golang/freetype
```

### 绘制文字

打开 service/article_service/article_poster.go 文件，增加绘制文字的业务逻辑，如下：

```go
type DrawText struct {
	JPG    draw.Image
	Merged *os.File

	Title string
	X0    int
	Y0    int
	Size0 float64

	SubTitle string
	X1       int
	Y1       int
	Size1    float64
}

func (a *ArticlePosterBg) DrawPoster(d *DrawText, fontName string) error {
	fontSource := setting.AppSetting.RuntimeRootPath + setting.AppSetting.FontSavePath + fontName
	fontSourceBytes, err := ioutil.ReadFile(fontSource)
	if err != nil {
		return err
	}

	trueTypeFont, err := freetype.ParseFont(fontSourceBytes)
	if err != nil {
		return err
	}

	fc := freetype.NewContext()
	fc.SetDPI(72)
	fc.SetFont(trueTypeFont)
	fc.SetFontSize(d.Size0)
	fc.SetClip(d.JPG.Bounds())
	fc.SetDst(d.JPG)
	fc.SetSrc(image.Black)

	pt := freetype.Pt(d.X0, d.Y0)
	_, err = fc.DrawString(d.Title, pt)
	if err != nil {
		return err
	}

	fc.SetFontSize(d.Size1)
	_, err = fc.DrawString(d.SubTitle, freetype.Pt(d.X1, d.Y1))
	if err != nil {
		return err
	}

	err = jpeg.Encode(d.Merged, d.JPG, nil)
	if err != nil {
		return err
	}

	return nil
}
```

这里主要使用了 freetype 包，分别涉及如下细项：

1、freetype.NewContext：创建一个新的 Context，会对其设置一些默认值

```go
func NewContext() *Context {
	return &Context{
		r:        raster.NewRasterizer(0, 0),
		fontSize: 12,
		dpi:      72,
		scale:    12 << 6,
	}
}
```

2、fc.SetDPI：设置屏幕每英寸的分辨率

3、fc.SetFont：设置用于绘制文本的字体

4、fc.SetFontSize：以磅为单位设置字体大小

5、fc.SetClip：设置剪裁矩形以进行绘制

6、fc.SetDst：设置目标图像

7、fc.SetSrc：设置绘制操作的源图像，通常为 [image.Uniform](https://golang.org/pkg/image/#Uniform)

```go
var (
        // Black is an opaque black uniform image.
        Black = NewUniform(color.Black)
        // White is an opaque white uniform image.
        White = NewUniform(color.White)
        // Transparent is a fully transparent uniform image.
        Transparent = NewUniform(color.Transparent)
        // Opaque is a fully opaque uniform image.
        Opaque = NewUniform(color.Opaque)
)
```

8、fc.DrawString：根据 Pt 的坐标值绘制给定的文本内容

### 业务逻辑

打开 service/article_service/article_poster.go 方法，在 Generate 方法增加绘制文字的代码逻辑，如下：

```go
func (a *ArticlePosterBg) Generate() (string, string, error) {
	fullPath := qrcode.GetQrCodeFullPath()
	fileName, path, err := a.Qr.Encode(fullPath)
	if err != nil {
		return "", "", err
	}

	if !a.CheckMergedImage(path) {
		...

		draw.Draw(jpg, jpg.Bounds(), bgImage, bgImage.Bounds().Min, draw.Over)
		draw.Draw(jpg, jpg.Bounds(), qrImage, qrImage.Bounds().Min.Sub(image.Pt(a.Pt.X, a.Pt.Y)), draw.Over)

		err = a.DrawPoster(&DrawText{
			JPG:    jpg,
			Merged: mergedF,

			Title: "Golang Gin 系列文章",
			X0:    80,
			Y0:    160,
			Size0: 42,

			SubTitle: "---煎鱼",
			X1:       320,
			Y1:       220,
			Size1:    36,
		}, "msyhbd.ttc")

		if err != nil {
			return "", "", err
		}
	}

	return fileName, path, nil
}
```

## 验证

访问生成文章海报的接口 `$HOST/api/v1/articles/poster/generate?token=$token`，检查其生成结果，如下图

![image](https://s2.ax1x.com/2020/02/15/1xKBTS.jpg)

## 总结

在本章节在 [连载十五](https://github.com/EDDYCJY/blog/blob/master/golang/gin/2018-07-04-Gin%E5%AE%9E%E8%B7%B5-%E8%BF%9E%E8%BD%BD%E5%8D%81%E4%BA%94-%E7%94%9F%E6%88%90%E4%BA%8C%E7%BB%B4%E7%A0%81-%E5%90%88%E5%B9%B6%E6%B5%B7%E6%8A%A5.md) 的基础上增加了绘制文字，在实现上并不困难，而这两块需求一般会同时出现，大家可以多加练习，了解里面的逻辑和其他 API 😁

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 02 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-08-26-makefile.md
================================================
---

title:      "「番外」请入门 Makefile"
date:       2018-08-26 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
--- 

## 知识点

- 写一个 Makefile

## 本文目标

含一定复杂度的软件工程，基本上都是先编译 A，再依赖 B，再编译 C...，最后才执行构建。如果每次都人为编排，又或是每新来一个同事就问你项目 D 怎么构建、重新构建需要注意什么...等等情况，岂不是要崩溃？

我们常常会在开源项目中发现 Makefile，你是否有过疑问？

本章节会简单介绍 Makefile 的使用方式，最后建议深入学习。

## 怎么解决

对于构建编排，Docker 有 Dockerfile ，在 Unix 中有神器 [Make](https://en.wikipedia.org/wiki/Make_%28software%29) ....

## Make

### 是什么

Make 是一个构建自动化工具，会在当前目录下寻找 Makefile 或 makefile 文件。如果存在，会依据 Makefile 的**构建规则**去完成构建

当然了，实际上 Makefile 内都是你根据 make 语法规则，自己编写的特定 Shell 命令等

它是一个工具，规则也很简单。在支持的范围内，编译 A， 依赖 B，再编译 C，完全没问题

### 规则

Makefile 由多条规则组成，每条规则都以一个 target（目标）开头，后跟一个 : 冒号，冒号后是这一个目标的 prerequisites（前置条件）

紧接着新的一行，必须以一个 tab 作为开头，后面跟随 command（命令），也就是你希望这一个 target 所执行的构建命令

```
[target] ... : [prerequisites] ...
<tab>[command]
    ...
    ...
```

- target：一个目标代表一条规则，可以是一个或多个文件名。也可以是某个操作的名字（标签），称为**伪目标（phony）**
- prerequisites：前置条件，这一项是**可选参数**。通常是多个文件名、伪目标。它的作用是 target 是否需要重新构建的标准，如果前置条件不存在或有过更新（文件的最后一次修改时间）则认为 target 需要重新构建
- command：构建这一个 target 的具体命令集

### 简单的例子

本文将以 [go-gin-example](https://github.com/EDDYCJY/go-gin-example) 去编写 Makefile 文件，请跨入 make 的大门

#### 分析

在编写 Makefile 前，需要先分析构建先后顺序、依赖项，需要解决的问题等

#### 编写

```makefile
.PHONY: build clean tool lint help

all: build

build:
	go build -v .

tool:
	go tool vet . |& grep -v vendor; true
	gofmt -w .

lint:
	golint ./...

clean:
	rm -rf go-gin-example
	go clean -i .

help:
	@echo "make: compile packages and dependencies"
	@echo "make tool: run specified go tool"
	@echo "make lint: golint ./..."
	@echo "make clean: remove object files and cached files"
```

1、在上述文件中，使用了 `.PHONY`，其作用是声明 build / clean / tool / lint / help 为**伪目标**，声明为伪目标会怎么样呢？

- 声明为伪目标后：在执行对应的命令时，make 就不会去检查是否存在 build / clean / tool / lint / help 其对应的文件，而是每次都会运行标签对应的命令

- 若不声明：恰好存在对应的文件，则 make 将会认为 xx 文件已存在，没有重新构建的必要了

2、这块比较简单，在命令行执行即可看见效果，实现了以下功能：

1. make: make 就是 make all
2. make build: 编译当前项目的包和依赖项
3. make tool: 运行指定的 Go 工具集
4. make lint: golint 一下
5. make clean: 删除对象文件和缓存文件
6. make help: help

#### 为什么会打印执行的命令

如果你实际操作过，可能会有疑问。明明只是执行命令，为什么会打印到标准输出上了？

##### 原因

make 默认会打印每条命令，再执行。这个行为被定义为**回声**

##### 解决

可以在对应命令前加上 @，可指定该命令不被打印到标准输出上

```makefile
build:
	@go build -v .
```

那么还有其他的特殊符号吗？有的，请课后去了解下 +、- 的用途 🤩

## 小结

这是一篇比较简洁的文章，希望可以让您对 Makefile 有一个基本了解。

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gin/2018-09-01-nginx.md
================================================
---

title:      "「连载十七」用Nginx部署Go应用"
date:       2018-09-01 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - gin
--- 

## 知识点

- Nginx。
- 反向代理。

## 本文目标

简单部署后端服务。

## 做什么

在本章节，我们将简单介绍 Nginx 以及使用 Nginx 来完成对 [go-gin-example](https://github.com/EDDYCJY/go-gin-example) 的部署，会实现反向代理和简单负载均衡的功能。

## Nginx

### 是什么

Nginx 是一个 Web Server，可以用作反向代理、负载均衡、邮件代理、TCP / UDP、HTTP 服务器等等，它拥有很多吸引人的特性，例如：

- 以较低的内存占用率处理 10,000 多个并发连接（每 10k 非活动 HTTP 保持活动连接约 2.5 MB ）
- 静态服务器（处理静态文件）
- 正向、反向代理
- 负载均衡
- 通过 OpenSSL 对 TLS / SSL 与 SNI 和 OCSP 支持
- FastCGI、SCGI、uWSGI 的支持
- WebSockets、HTTP/1.1 的支持
- Nginx + Lua

### 安装

请右拐谷歌或百度，安装好 Nginx 以备接下来的使用

### 简单讲解

#### 常用命令

- nginx：启动 Nginx
- nginx -s stop：立刻停止 Nginx 服务
- nginx -s reload：重新加载配置文件
- nginx -s quit：平滑停止 Nginx 服务
- nginx -t：测试配置文件是否正确
- nginx -v：显示 Nginx 版本信息
- nginx -V：显示 Nginx 版本信息、编译器和配置参数的信息

#### 涉及配置

1、 proxy_pass：配置**反向代理的路径**。需要注意的是如果 proxy_pass 的 url 最后为
/，则表示绝对路径。否则（不含变量下）表示相对路径，所有的路径都会被代理过去

2、 upstream：配置**负载均衡**，upstream 默认是以轮询的方式进行负载，另外还支持**四种模式**，分别是：

（1）weight：权重，指定轮询的概率，weight 与访问概率成正比

（2）ip_hash：按照访问 IP 的 hash 结果值分配

（3）fair：按后端服务器响应时间进行分配，响应时间越短优先级别越高

（4）url_hash：按照访问 URL 的 hash 结果值分配

## 部署

在这里需要对 nginx.conf 进行配置，如果你不知道对应的配置文件是哪个，可执行 `nginx -t` 看一下

```
$ nginx -t
nginx: the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /usr/local/etc/nginx/nginx.conf test is successful
```

显然，我的配置文件在 `/usr/local/etc/nginx/` 目录下，并且测试通过

### 反向代理

反向代理是指以代理服务器来接受网络上的连接请求，然后将请求转发给内部网络上的服务器，并将从服务器上得到的结果返回给请求连接的客户端，此时代理服务器对外就表现为一个反向代理服务器。（来自[百科](https://baike.baidu.com/item/%E5%8F%8D%E5%90%91%E4%BB%A3%E7%90%86/7793488?fr=aladdin)）

![image](https://s2.ax1x.com/2020/02/15/1xlQe0.png)

#### 配置 hosts

由于需要用本机作为演示，因此先把映射配上去，打开 `/etc/hosts`，增加内容：

```
127.0.0.1       api.blog.com
```

#### 配置 nginx.conf

打开 nginx 的配置文件 nginx.conf（我的是 /usr/local/etc/nginx/nginx.conf），我们做了如下事情：

增加 server 片段的内容，设置 server_name 为 api.blog.com 并且监听 8081 端口，将所有路径转发到 `http://127.0.0.1:8000/` 下

```
worker_processes  1;

events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    server {
        listen       8081;
        server_name  api.blog.com;

        location / {
            proxy_pass http://127.0.0.1:8000/;
        }
    }
}
```

#### 验证

##### 启动 go-gin-example

回到 [go-gin-example](github.com/EDDYCJY/go-gin-example) 的项目下，执行 make，再运行 ./go-gin-exmaple

```sh
$ make
github.com/EDDYCJY/go-gin-example
$ ls
LICENSE        README.md      conf           go-gin-example middleware     pkg            runtime        vendor
Makefile       README_ZH.md   docs           main.go        models         routers        service
$ ./go-gin-example
...
[GIN-debug] DELETE /api/v1/articles/:id      --> github.com/EDDYCJY/go-gin-example/routers/api/v1.DeleteArticle (4 handlers)
[GIN-debug] POST   /api/v1/articles/poster/generate --> github.com/EDDYCJY/go-gin-example/routers/api/v1.GenerateArticlePoster (4 handlers)
Actual pid is 14672
```

##### 重启 nginx

```sh
$ nginx -t
nginx: the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /usr/local/etc/nginx/nginx.conf test is successful
$ nginx -s reload
```

##### 访问接口

![image](https://s2.ax1x.com/2020/02/15/1xlEFS.jpg)

如此，就实现了一个简单的反向代理了，是不是很简单呢

### 负载均衡

负载均衡，英文名称为 Load Balance（常称 LB），其意思就是分摊到多个操作单元上进行执行（来自百科）

你能从运维口中经常听见，XXX 负载怎么突然那么高。 那么它到底是什么呢？

其背后一般有多台 server，系统会根据配置的策略（例如 Nginx 有提供四种选择）来进行动态调整，尽可能的达到各节点均衡，从而提高系统整体的吞吐量和快速响应

#### 如何演示

前提条件为多个后端服务，那么势必需要多个 [go-gin-example](https://github.com/EDDYCJY/go-gin-example)，为了演示我们可以启动多个端口，达到模拟的效果

为了便于演示，分别在启动前将 conf/app.ini 的应用端口修改为 8001 和 8002（也可以做成传入参数的模式），达到启动 2 个监听 8001 和 8002 的后端服务

#### 配置 nginx.conf

回到 nginx.conf 的老地方，增加负载均衡所需的配置。新增 upstream 节点，设置其对应的 2 个后端服务，最后修改了 proxy_pass 指向（格式为 http:// + upstream 的节点名称）

```
worker_processes  1;

events {
    worker_connections  1024;
}


http {
    include       mime.types;
    default_type  application/octet-stream;

    sendfile        on;
    keepalive_timeout  65;

    upstream api.blog.com {
        server 127.0.0.1:8001;
        server 127.0.0.1:8002;
    }

    server {
        listen       8081;
        server_name  api.blog.com;

        location / {
            proxy_pass http://api.blog.com/;
        }
    }
}
```

##### 重启 nginx

```sh
$ nginx -t
nginx: the configuration file /usr/local/etc/nginx/nginx.conf syntax is ok
nginx: configuration file /usr/local/etc/nginx/nginx.conf test is successful
$ nginx -s reload
```

#### 验证

再重复访问 `http://api.blog.com:8081/auth?username={USER_NAME}}&password={PASSWORD}`，多访问几次便于查看效果

目前 Nginx 没有进行特殊配置，那么它是轮询策略，而 go-gin-example 默认开着 debug 模式，看看请求 log 就明白了

![image](https://s2.ax1x.com/2020/02/15/1xlZWQ.jpg)

![image](https://s2.ax1x.com/2020/02/15/1xlnQs.jpg)

## 总结

在本章节，希望您能够简单习得日常使用的 Web Server 背后都是一些什么逻辑，Nginx 是什么？反向代理？负载均衡？

怎么简单部署，知道了吧。

## 参考

### 本系列示例代码

- [go-gin-example](https://github.com/EDDYCJY/go-gin-example)

## 关于

### 修改记录

- 第一版：2018 年 02 月 16 日发布文章
- 第二版：2019 年 10 月 01 日修改文章

## ？

如果有任何疑问或错误，欢迎在 [issues](https://github.com/EDDYCJY/blog) 进行提问或给予修正意见，如果喜欢或对你有所帮助，欢迎 Star，对作者是一种鼓励和推进。

### 我的公众号

![image](https://image.eddycjy.com/8d0b0c3a11e74efd5fdfd7910257e70b.jpg)

================================================
FILE: content/posts/go/gmp-why-p.md
================================================
---
title: "经典面试题：你觉得 Go 在什么时候会抢占 P？"
date: 2021-06-24T12:42:05+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天我们有聊到《单核 CPU，开两个 Goroutine，其中一个死循环，会怎么样？》的问题，我们在一个细节部分有提到：

![](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6d9cdfb09590496daeca3675aae08611~tplv-k3u1fbpfcp-zoom-1.image)

有新的小伙伴会产生更多的疑问，那就是在 Go 语言中，是如何抢占 P 的呢，这里面是怎么做的？

今天这篇文章我们就来解密抢占 P。

## 调度器的发展史

在 Go 语言中，Goroutine 早期是没有设计成抢占式的，早期 Goroutine 只有读写、主动让出、锁等操作时才会触发调度切换。

这样有一个严重的问题，就是垃圾回收器进行 STW 时，如果有一个 Goroutine 一直都在阻塞调用，垃圾回收器就会一直等待他，不知道等到什么时候...

这种情况下就需要抢占式调度来解决问题。如果一个 Goroutine 运行时间过久，就需要进行抢占来解决。

这块 Go 语言在 Go1.2 起开始实现抢占式调度器，不断完善直至今日：
- Go0.x：基于单线程的程调度器。
- Go1.0：基于多线程的调度器。
- Go1.1：基于任务窃取的调度器。
- Go1.2 - Go1.13：基于协作的抢占式调度器。
- Go1.14：基于信号的抢占式调度器。

调度器的新提案：非均匀存储器访问调度（Non-uniform memory access，NUMA），
但由于实现过于复杂，优先级也不够高，因此迟迟未提上日程。

有兴趣的小伙伴可以详见 Dmitry Vyukov, dvyukov 所提出的 [NUMA-aware scheduler for Go](https://docs.google.com/document/u/0/d/1d3iI2QWURgDIsSR6G2275vMeQ_X7w-qxM2Vp7iGwwuM/pub)。

## 为什么要抢占 P

为什么会要想去抢占 P 呢，说白了就是不抢，就没机会运行，会 hang 死。又或是资源分配不均了，

这在调度器设计中显然是不合理的。

跟这个例子一样：

```golang
// Main Goroutine 
func main() {
    // 模拟单核 CPU
    runtime.GOMAXPROCS(1)
    
    // 模拟 Goroutine 死循环
    go func() {
        for {
        }
    }()

    time.Sleep(time.Millisecond)
    fmt.Println("脑子进煎鱼了")
}
```

这个例子在老版本的 Go 语言中，就会一直阻塞，没法重见天日，是一个需要做抢占的场景。

但可能会有小伙伴问，抢占了，会不会有新问题。因为原本正在使用 P 的 M 就凉凉了（M 会与 P 进行绑定），没了 P 也就没法继续执行了。

这其实没有问题，因为该 Goroutine 已经阻塞在了系统调用上，暂时是不会有后续的执行新诉求。

但万一代码是在运行了好一段时间后又能够运行了（业务上也允许长等待），也就是该 Goroutine 从阻塞状态中恢复了，期望继续运行，没了 P 怎么办？

这时候该 Goroutine 可以和其他 Goroutine 一样，先检查自身所在的 M 是否仍然绑定着 P：
- 若是有 P，则可以调整状态，继续运行。
- 若是没有 P，可以重新抢 P，再占有并绑定 P，为自己所用。

也就是抢占 P，本身就是一个双向行为，你抢了我的 P，我也可以去抢别人的 P 来继续运行。

## 怎么抢占 P

讲解了为什么要抢占 P 的原因后，我们进一步深挖，“他” 是怎么抢占到具体的 P 的呢？

这就涉及到前文所提到的 `runtime.retake` 方法了，其处理以下两种场景：
- 抢占阻塞在系统调用上的 P。
- 抢占运行时间过长的 G。

在此主要针对抢占 P 的场景，分析如下：

```golang
func retake(now int64) uint32 {
	n := 0
	// 防止发生变更，对所有 P 加锁
	lock(&allpLock)
	// 走入主逻辑，对所有 P 开始循环处理
	for i := 0; i < len(allp); i++ {
		_p_ := allp[i]
		pd := &_p_.sysmontick
		s := _p_.status
		sysretake := false
		...
		if s == _Psyscall {
			// 判断是否超过 1 个 sysmon tick 周期
			t := int64(_p_.syscalltick)
			if !sysretake && int64(pd.syscalltick) != t {
				pd.syscalltick = uint32(t)
				pd.syscallwhen = now
				continue
			}
      
			...
		}
	}
	unlock(&allpLock)
	return uint32(n)
}
```

该方法会先对 `allpLock` 上锁，这个变量含义如其名，`allpLock` 可以防止该数组发生变化。

其会保护 `allp`、`idlepMask` 和 `timerpMask` 属性的无 `P` 读取和大小变化，以及对 `allp` 的所有写入操作，可以避免影响后续的操作。

### 场景一

前置处理完毕后，进入主逻辑，会使用万能的 `for` 循环对所有的 P（allp）进行一个个处理。

```golang
			t := int64(_p_.syscalltick)
			if !sysretake && int64(pd.syscalltick) != t {
				pd.syscalltick = uint32(t)
				pd.syscallwhen = now
				continue
			}
```

第一个场景是：会对 `syscalltick` 进行判定，如果在系统调用（syscall）中存在超过 1 个 sysmon tick 周期（至少 20us）的任务，则会从系统调用中抢占 P，否则跳过。

### 场景二

如果未满足会继续往下，走到如下逻辑：

```golang
func retake(now int64) uint32 {
	for i := 0; i < len(allp); i++ {
		...
		if s == _Psyscall {
			// 从此处开始分析
			if runqempty(_p_) && 
      atomic.Load(&sched.nmspinning)+atomic.Load(&sched.npidle) > 0 && 
      pd.syscallwhen+10*1000*1000 > now {
				continue
			}
			...
		}
	}
	unlock(&allpLock)
	return uint32(n)
}
```
第二个场景，聚焦到这一长串的判断中：
- `runqempty(_p_) == true` 方法会判断任务队列 P 是否为空，以此来检测有没有其他任务需要执行。
- `atomic.Load(&sched.nmspinning)+atomic.Load(&sched.npidle) > 0` 会判断是否存在空闲 P 和正在进行调度窃取 G 的 P。
- `pd.syscallwhen+10*1000*1000 > now` 会判断系统调用时间是否超过了 10ms。

这里奇怪的是 `runqempty` 方法明明已经判断了没有其他任务，这就代表了没有任务需要执行，是不需要抢夺 P 的。

但实际情况是，由于可能会阻止 sysmon 线程的深度睡眠，最终还是希望继续占有 P。

在完成上述判断后，进入到抢夺 P 的阶段：

```golang
func retake(now int64) uint32 {
	for i := 0; i < len(allp); i++ {
		...
		if s == _Psyscall {
			// 承接上半部分
			unlock(&allpLock)
			incidlelocked(-1)
			if atomic.Cas(&_p_.status, s, _Pidle) {
				if trace.enabled {
					traceGoSysBlock(_p_)
					traceProcStop(_p_)
				}
				n++
				_p_.syscalltick++
				handoffp(_p_)
			}
			incidlelocked(1)
			lock(&allpLock)
		}
	}
	unlock(&allpLock)
	return uint32(n)
}
```

- 解锁相关属性：需要调用 `unlock` 方法解锁 `allpLock`，从而实现获取 `sched.lock`，以便继续下一步。
- 减少闲置 M：需要在原子操作（CAS）之前减少闲置 M 的数量（假设有一个正在运行）。 否则在发生抢夺 M 时可能会退出系统调用，递增 nmidle 并报告死锁事件。
- 修改 P 状态：调用 `atomic.Cas` 方法将所抢夺的 P 状态设为 idle，以便于交于其他 M 使用。
- 抢夺 P 和调控 M：调用 `handoffp` 方法从系统调用或锁定的 M 中抢夺 P，会由新的 M 接管这个 P。

## 总结

至此完成了抢占 P 的基本流程，我们可得出满足以下条件：
1. 如果存在系统调用超时：存在超过 1 个 sysmon tick 周期（至少 20us）的任务，则会从系统调用中抢占 P。
2. 如果没有空闲的 P：所有的 P 都已经与 M 绑定。需要抢占当前正处于系统调用之，而实际上系统调用并不需要的这个 P 的情况，会将其分配给其它 M 去调度其它 G。
3. 如果 P 的运行队列里面有等待运行的 G，为了保证 P 的本地队列中的 G 得到及时调度。而自己本身的 P 又忙于系统调用，无暇管理。此时会寻找另外一个 M 来接管 P，从而实现继续调度 G 的目的。

## 参考

- [NUMA-aware scheduler for Go](https://docs.google.com/document/u/0/d/1d3iI2QWURgDIsSR6G2275vMeQ_X7w-qxM2Vp7iGwwuM/pub)
- [go-under-the-hood](https://golang.design/under-the-hood/zh-cn/part2runtime/ch06sched/preemption/#p-)
- [深入解析 Go-抢占式调度](https://tiancaiamao.gitbooks.io/go-internals/content/zh/05.5.html)
- [Go语言调度器源代码情景分析](https://cloud.tencent.com/developer/article/1450290)

================================================
FILE: content/posts/go/go-array-slice.md
================================================
---
title: "Go 数组比切片好在哪？"
date: 2021-09-17T12:43:08+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间有播放一条快讯，就是 Go1.17 会正式支持切片（Slice）转换到数据（Array），不再需要用以前那种骚办法了，安全了许多。

但是也有同学提出了新的疑惑，在 Go 语言中，数组其实是用的相对较少的，甚至会有同学认为在 Go 里可以把数组给去掉。

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9764cd832d1e4875953b66434beab8e4~tplv-k3u1fbpfcp-zoom-1.image)

数组相较切片到底有什么优势，我们又应该在什么场景下使用呢？

这是一个我们需要深究的问题，因此今天就跟大家一起来一探究竟，本文会先简单介绍数组和切片是什么，再进一步对数组的使用场景剖析。

一起愉快地开始吸鱼之路。

数组是什么
-----

Go 语言中有一种基本数据类型，叫数组。其格式为：`[n]T`。是一个包含 N 个类型 T 的值的数组。

基本声明格式为：

```
var a [10]int

```

代表的是声明了一个变量 a 是一个包含 10 个整数的数组。数组的长度是其类型的一部分，所以数组不能被随意调整大小。

在使用例子上：

```
func main() {
 var a [2]string
 a[0] = "脑子进"
 a[1] = "煎鱼了"
 fmt.Println(a[0], a[1])
 fmt.Println(a)

 primes := [6]int{2, 3, 5, 7, 11, 13}
 fmt.Println(primes)
}

```

输出结果：

```
脑子进 煎鱼了
[脑子进 煎鱼了]
[2 3 5 7 11 13]

```

在赋值和访问上，数组可以针对不同的索引，进行单独操作。在内存布局上，数组的索引 0 和 1...是会在相邻区域，可直接访问。

切片是什么
-----

为什么数组在业务代码似乎用的很少。因为 Go 语言有一个切片的数据类型：

基本声明格式为：

```
var a []T

```

代表的是变量 a 是带有类型元素的切片T。通过指定两个索引（下限和上限）并用冒号隔开来形成切片：

```
a[low : high]

```

在使用例子上：

```
func main() {
 primes := [3]string{"煎鱼", "搞", "Go"}

 var s []string = primes[1:3]
 fmt.Println(s)
}

```

输出结果：

```
[搞 Go]

```

切片支持动态的扩缩容，不需要用户侧去关注，非常便利。更重要的一点是，切片的底层数据结构中本身就包含了数组：

```
type slice struct {
 array unsafe.Pointer
 len   int
 cap   int
}

```

也就很多人笑称：**在 Go 语言中数组已经可以下岗了，用切片就完事了**...

你怎么看待这个说法的呢，快速思考你心中的答案。

数组的优势
-----

在风尘仆仆介绍完数组和切片的基本场景后，在数组的优势方面，先了解一下官方的自述：

> > Arrays are useful when planning the detailed layout of memory and sometimes can help avoid allocation, but primarily they are a building block for slices.

非常粗暴间接：在规划内存的详细布局时，数组是很有用的，有时可以帮助避免分配，但主要是它们是分片的构建块。

我们再进一步解读，看看官方这股 “密文” 具体指的是什么，我们将该密文解读为以下内容进行讲解：

*   可比较。
    
*   编译安全。
    
*   长度是类型。
    
*   规划内存布局。
    
*   访问速度。
    

### 可比较

数组是固定长度的，它们之间是可以进行比较的，数组是值对象（不是引用或指针类型），你不会遇到 interface 等比较的误判：

```
func main() {
 a1 := [3]string{"脑子", "进", "煎鱼了"}
 a2 := [3]string{"煎鱼", "进", "脑子了"}
 a3 := [3]string{"脑子", "进", "煎鱼了"}

 fmt.Println(a1 == a2, a1 == a3)
}

```

输出结果：

```
false true

```

另一方面，切片不可以直接比较，也不能用于判断：

```
func main() {
 a1 := []string{"脑子", "进", "煎鱼了"}
 a2 := []string{"煎鱼", "进", "脑子了"}
 a3 := []string{"脑子", "进", "煎鱼了"}

 fmt.Println(a1 == a2, a1 == a3)
}

```

输出结果：

```
# command-line-arguments
./main.go:10:17: invalid operation: a1 == a2 (slice can only be compared to nil)
./main.go:10:27: invalid operation: a1 == a3 (slice can only be compared to nil)

```

同时数组可以作为 map 的 k（键），而切片不行，切片并没有实现平等运算符（equality operator），需要考虑的问题有非常多，例如：

*   涉及浅层与深层比较。
    
*   指针与值比较。
    
*   如何处理递归类型。
    

平等是为结构体和数组定义的，所以这类类型可以作为 map 键使用。切片没有平等的定义，有着非常根本的差距。

数组的可比较和平等，切片做不到。

### 编译安全

数组可以提供更高的编译时安全，可以在编译时检查索引范围。如下：

```
s := make([]int, 3)
s[3] = 3 // "Only" a runtime panic: runtime error: index out of range

a := [3]int{}
a[3] = 3 // Compile-time error: invalid array index 3 (out of bounds for 3-element array)

```

这个编译检查的帮助虽 “小”，但其实非常有意义。我是日常看到各大切片越界的告警，感觉都能背下来了...

万一这个越界是在 hot path 上，影响大量用户，分分钟背个事故，再来个 3.25，岂不梦中惊醒？

数组的编译安全，切片做不到。

### 长度是类型

数组的长度是数组类型声明的一部分，因此**长度不同的数组是不同的类型**，两个就不是一个 “东西”。

当然，这是一把双刃剑。其优势在于：可用于显式指定所需数组的长度。

例如：你在业务代码中想编写一个使用 IPv4 地址的函数。可以声明 `type [4]byte`。使用数组有以下意识：

*   有了编译时的保证，也就是达到传递给你的函数的值将恰好具有4个字节，不多也不少的效果。
    
*   如果长度不对，也就可以认为是无效的 IPv4 地址，非常方便。
    

同时数组的长度，也可以用做记录目的：

*   MD5 类型，在 `crypto/md5`包中，`md5.Sum` 方法返回类型为的值，`[Size]byte` 其中 `md5.Size` 一个常量为16：MD5 校验和的长度。
    
*   IPv4 类型，所声明的 `[4]byte` 正确记录了有 4 个字节。
    
*   RGB 类型，所声明的 `[3]byte` 告诉有对每个颜色成分 1 个字节。
    

在特定业务场景上，使用数组更好。

### 规划内存布局

数组可以更好地控制内存布局，因为不能直接在带有切片的结构中分配空间，所以可以使用数组来解决。

例如：

```
type Foo struct {
    buf [64]byte
}

```

不知道你是否有在一些 Go 图形库上见过这种不明所以的操作，例子如下：

```
type TGIHeader struct {
    _        uint16 // Reserved
    _        uint16 // Reserved
    Width    uint32
    Height   uint32
    _        [15]uint32 // 15 "don't care" dwords
    SaveTime int64
}

```

因为业务需求，我们需要实现一个格式，其中格式是 "TGI"（理论上的Go Image），头包含这样的字段：

*   有 2 个保留字（每个16位）。
    
*   有 1 个字的图像宽度。
    
*   有 1 个字的图像高度。
    
*   有 15 个业务 "不在乎 "的字节。
    
*   有 1 个保存时间，图像的保存时间为8字节，是自1970年1月1日UTC以来的纳秒数。
    

这么一看，也就不难理解数组的在这个场景下的优势了。定长，可控的内存，在计划内存布局时非常有用。

### 访问速度

使用数组时，其访问（单个）数组元素比访问切片元素更高效，时间复杂度是 O（1）。例如：

```
 var a [2]string
 a[0] = "脑子进"
 a[1] = "煎鱼了"
 fmt.Println(a[0], a[1])

```

切片就没那么方便了，访问某个位置上的索引值，需要：

```
 var a []int{0, 1, 2, 3, 4, 5}  
  number := numbers[1:3]

```

相对复杂些的，删除指定索引位上的值，可能还有小伙伴纠结半天，甚至在找第三方开源库想快速实现。

无论在访问速度和开发效率上，数组都占一定的优势，这是切片所无法直接对比的。

总结
--

经过一轮的探讨，我们对 Go 语言的数组有了更深入的理解。总结如下：

*   数组是值对象，可以进行比较，可以将数组用作 map 的映射键。而这些，切片都不可以，不能比较，无法作为 map 的映射键。
    
*   数组有编译安全的检查，可以在早起就避免越界行为。切片是在运行时会出现越界的 panic，阶段不同。
    
*   数组可以更好地控制内存布局，若拿切片替换，会发现不能直接在带有切片的结构中分配空间，数组可以。
    
*   数组在访问单个元素时，性能比切片好。
    
*   数组的长度，是类型的一部分。在特定场景下具有一定的意义。
    
*   数组是切片的基础，每个数组都可以是一个切片，但并非每个切片都可以是一个数组。如果值是固定大小，可以通过使用数组来获得较小的性能提升（至少节省 slice 头占用的空间）。
    

与你心目中的数组的优势是否一致呢，欢迎大家在评论区进行讨论和交流。

我是煎鱼，咱们下期再见：）


参考
--

*   In GO programming language what are the benefits of using Arrays over Slices?
    
*   Why have arrays in Go?

================================================
FILE: content/posts/go/go-bootstrap.md
================================================
---
title: "Go 应用程序是怎么运行起来的？"
date: 2020-10-08T15:57:18+08:00
toc: true
images:
tags: 
  - go
---

自古应用程序均从 Hello World 开始，你我所写的 Go 语言亦然：

```
import "fmt"

func main() {
	fmt.Println("hello world.")
}
```

这段程序的输出结果为 `hello world.`，就是这么的简单又直接。但这时候又不禁思考了起来，这个 `hello world.` 是怎么输出来，经历了什么过程。

真是非常的好奇，今天我们就通过这篇文章来一探究竟。

## 引导阶段

### 查找入口

开始剖析之路，首先编译上文提到的示例程序：

```shell
$ GOFLAGS="-ldflags=-compressdwarf=false" go build 
```

在命令中指定了 GOFLAGS 参数，这是因为在 Go1.11 起，为了减少二进制文件大小，调试信息会被压缩。导致在 MacOS 上使用 gdb 时无法理解压缩的 DWARF 的含义是什么（而我恰恰就是用的 MacOS）。

因此需要在本次调试中将其关闭，再使用 gdb 进行调试，以此达到观察的目的：

```shell
$ gdb awesomeProject 
(gdb) info files
Symbols from "/Users/eddycjy/go-application/awesomeProject/awesomeProject".
Local exec file:
	`/Users/eddycjy/go-application/awesomeProject/awesomeProject', file type mach-o-x86-64.
	Entry point: 0x1063c80
	0x0000000001001000 - 0x00000000010a6aca is .text
	...
(gdb) b *0x1063c80
Breakpoint 1 at 0x1063c80: file /usr/local/Cellar/go/1.15/libexec/src/runtime/rt0_darwin_amd64.s, line 8.
```

通过 Entry point 的调试，可看到真正的程序入口在 runtime 包中，不同的计算机架构指向不同，例如：MacOS 在 `src/runtime/rt0_darwin_amd64.s`，Linux 在 `src/runtime/rt0_linux_amd64.s`。

```
Breakpoint 1 at 0x1063c80: file /usr/local/Cellar/go/1.15/libexec/src/runtime/rt0_darwin_amd64.s, line 8.
```

其最终指向了 rt0_darwin_amd64.s 文件，这个文件名称非常的直观，rt0 代表 runtime0 的缩写，指代运行时的创世，超级奶爸；darwin 代表目标操作系统（GOOS），amd64 代表目标操作系统架构（GOHOSTARCH）。

同时 Go 语言还支持更多的目标系统架构，例如：AMD64、AMR、MIPS、WASM 等：

![image](https://image.eddycjy.com/981720dfbce750bec26fc394e97d9ff7.jpg)

若有兴趣可到 `src/runtime` 目录下进一步查看。

### 入口方法

在 rt0_linux_amd64.s 文件中，可发现 `_rt0_amd64_darwin` JMP 跳转到了 `_rt0_amd64` 方法：

```
TEXT _rt0_amd64_darwin(SB),NOSPLIT,$-8
	JMP	_rt0_amd64(SB)
...
```

紧接着又跳转到 `runtime·rt0_go` 方法：

```
TEXT _rt0_amd64(SB),NOSPLIT,$-8
	MOVQ	0(SP), DI	// argc
	LEAQ	8(SP), SI	// argv
	JMP	runtime·rt0_go(SB)
```

该方法将程序输入的 argc 和 argv 从内存移动到寄存器中。栈指针（SP）的前两个值分别是 argc 和 argv，其对应参数的数量和具体各参数的值。

### 开启主线

程序参数准备就绪后，正式初始化的方法落在 `runtime·rt0_go` 方法中：

```
TEXT runtime·rt0_go(SB),NOSPLIT,$0
	...
	CALL	runtime·check(SB)
	MOVL	16(SP), AX		// copy argc
	MOVL	AX, 0(SP)
	MOVQ	24(SP), AX		// copy argv
	MOVQ	AX, 8(SP)
	CALL	runtime·args(SB)
	CALL	runtime·osinit(SB)
	CALL	runtime·schedinit(SB)

	// create a new goroutine to start program
	MOVQ	$runtime·mainPC(SB), AX		// entry
	PUSHQ	AX
	PUSHQ	$0			// arg size
	CALL	runtime·newproc(SB)
	POPQ	AX
	POPQ	AX

	// start this M
	CALL	runtime·mstart(SB)
	...
```


- runtime.check：运行时类型检查，主要是校验编译器的翻译工作是否正确，是否有 “坑”。基本代码均为检查 `int8` 在 `unsafe.Sizeof` 方法下是否等于 1 这类动作。

- runtime.args：系统参数传递，主要是将系统参数转换传递给程序使用。

- runtime.osinit：系统基本参数设置，主要是获取 CPU 核心数和内存物理页大小。

- runtime.schedinit：进行各种运行时组件的初始化，包含调度器、内存分配器、堆、栈、GC 等一大堆初始化工作。是后续的重点关注对象。

- runtime·main：主要工作是运行 main goroutine，虽然在`runtime·rt0_go` 中指向的是`$runtime·mainPC` ，但实质指向的是 `runtime.main`。

- runtime.newproc：创建一个新的 goroutine 将其放入 g 的等待运行队列中去。且绑定 `runtime.main` 方法，也就是应用程序中的入口 main 方法。

- runtime.mstart：调度器开始进行循环调度。

在 `runtime·rt0_go` 方法中，其主要是完成各类运行时的检查，系统参数设置和获取，并进行大量的 Go 基础组件初始化。初始化完毕后进行 main goroutine 的运行，并放入等待队列（GMP），最后调度器开始进行循环调度。

## 总结

根据上述源码剖析，可以得出如下 Go 应用程序引导的流程图：

![image](https://image.eddycjy.com/057c1ccb06c16e8c5f38ff5800e3fa63.jpg)

在 Go 语言中，实际的运行入口并不是用户日常所写的 `main func`，更不是 `runtime.main` 方法，而是从 `rt0_*_amd64.s` 开始，最终再一路 JMP 到 `runtime·rt0_go` 里去，再在该方法里完成一系列 Go 自身所需要完成的绝大部分初始化动作。

其中包括运行时类型检查、系统参数传递、CPU 核数获取及设置、运行时组件的初始化（调度器、内存分配器、堆、栈、GC 等）、运行 main goroutine 和相应的 GMP 等大量缺省行为，还会涉及到调度器相关的大量知识。

后续将会继续剖析将进一步剖析 `runtime·rt0_go` 里的爱与恨，尤其像是 `runtime.main`、`runtime.schedinit` 等调度方法，都有非常大的学习价值，有兴趣的小伙伴可以持续关注。


================================================
FILE: content/posts/go/go-bootstrap0.md
================================================
---
title: "详解 Go 程序的启动流程，你知道 g0，m0 是什么吗？"
date: 2021-06-17T12:42:42+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。

自古应用程序均从 Hello World 开始，你我所写的 Go 语言亦然：

```
import "fmt"

func main() {
	fmt.Println("hello world.")
}
```

这段程序的输出结果为 `hello world.`，就是这么的简单又直接。但这时候又不禁思考了起来，这个 `hello world.` 是怎么输出来，经历了什么过程。

真是非常的好奇，今天我们就一起来探一探 Go 程序的启动流程。
其中涉及到 Go Runtime 的调度器启动，g0，m0 又是什么？

车门焊死，正式开始吸鱼之路。

## Go 引导阶段

### 查找入口

首先编译上文提到的示例程序：

```shell
$ GOFLAGS="-ldflags=-compressdwarf=false" go build 
```

在命令中指定了 GOFLAGS 参数，这是因为在 Go1.11 起，为了减少二进制文件大小，调试信息会被压缩。导致在 MacOS 上使用 gdb 时无法理解压缩的 DWARF 的含义是什么（而我恰恰就是用的 MacOS）。

因此需要在本次调试中将其关闭，再使用 gdb 进行调试，以此达到观察的目的：

```shell
$ gdb awesomeProject 
(gdb) info files
Symbols from "/Users/eddycjy/go-application/awesomeProject/awesomeProject".
Local exec file:
	`/Users/eddycjy/go-application/awesomeProject/awesomeProject', file type mach-o-x86-64.
	Entry point: 0x1063c80
	0x0000000001001000 - 0x00000000010a6aca is .text
	...
(gdb) b *0x1063c80
Breakpoint 1 at 0x1063c80: file /usr/local/Cellar/go/1.15/libexec/src/runtime/rt0_darwin_amd64.s, line 8.
```

通过 Entry point 的调试，可看到真正的程序入口在 runtime 包中，不同的计算机架构指向不同。例如：
- MacOS 在 `src/runtime/rt0_darwin_amd64.s`。
- Linux 在 `src/runtime/rt0_linux_amd64.s`。

其最终指向了 rt0_darwin_amd64.s 文件，这个文件名称非常的直观：

```
Breakpoint 1 at 0x1063c80: file /usr/local/Cellar/go/1.15/libexec/src/runtime/rt0_darwin_amd64.s, line 8.
```

rt0 代表 runtime0 的缩写，指代运行时的创世，超级奶爸：
- darwin 代表目标操作系统（GOOS）。
- amd64 代表目标操作系统架构（GOHOSTARCH）。

同时 Go 语言还支持更多的目标系统架构，例如：AMD64、AMR、MIPS、WASM 等：

![源码目录](https://image.eddycjy.com/981720dfbce750bec26fc394e97d9ff7.jpg)

若有兴趣可到 `src/runtime` 目录下进一步查看，这里就不一一介绍了。

### 入口方法

在 rt0_linux_amd64.s 文件中，可发现 `_rt0_amd64_darwin` JMP 跳转到了 `_rt0_amd64` 方法：

```
TEXT _rt0_amd64_darwin(SB),NOSPLIT,$-8
	JMP	_rt0_amd64(SB)
...
```

紧接着又跳转到 `runtime·rt0_go` 方法：

```
TEXT _rt0_amd64(SB),NOSPLIT,$-8
	MOVQ	0(SP), DI	// argc
	LEAQ	8(SP), SI	// argv
	JMP	runtime·rt0_go(SB)
```

该方法将程序输入的 argc 和 argv 从内存移动到寄存器中。

栈指针（SP）的前两个值分别是 argc 和 argv，其对应参数的数量和具体各参数的值。

### 开启主线

程序参数准备就绪后，正式初始化的方法落在 `runtime·rt0_go` 方法中：

```
TEXT runtime·rt0_go(SB),NOSPLIT,$0
	...
	CALL	runtime·check(SB)
	MOVL	16(SP), AX		// copy argc
	MOVL	AX, 0(SP)
	MOVQ	24(SP), AX		// copy argv
	MOVQ	AX, 8(SP)
	CALL	runtime·args(SB)
	CALL	runtime·osinit(SB)
	CALL	runtime·schedinit(SB)

	// create a new goroutine to start program
	MOVQ	$runtime·mainPC(SB), AX		// entry
	PUSHQ	AX
	PUSHQ	$0			// arg size
	CALL	runtime·newproc(SB)
	POPQ	AX
	POPQ	AX

	// start this M
	CALL	runtime·mstart(SB)
	...
```

- runtime.check：运行时类型检查，主要是校验编译器的翻译工作是否正确，是否有 “坑”。基本代码均为检查 `int8` 在 `unsafe.Sizeof` 方法下是否等于 1 这类动作。
- runtime.args：系统参数传递，主要是将系统参数转换传递给程序使用。
- runtime.osinit：系统基本参数设置，主要是获取 CPU 核心数和内存物理页大小。
- runtime.schedinit：进行各种运行时组件的初始化，包含调度器、内存分配器、堆、栈、GC 等一大堆初始化工作。会进行 p 的初始化，并将 m0 和某一个 p 进行绑定。
- runtime.main：主要工作是运行 main goroutine，虽然在`runtime·rt0_go` 中指向的是`$runtime·mainPC`，但实质指向的是 `runtime.main`。
- runtime.newproc：创建一个新的 goroutine，且绑定 `runtime.main` 方法（也就是应用程序中的入口 main 方法）。并将其放入 m0 绑定的p的本地队列中去，以便后续调度。
- runtime.mstart：启动 m，调度器开始进行循环调度。

在 `runtime·rt0_go` 方法中，其主要是完成各类运行时的检查，系统参数设置和获取，并进行大量的 Go 基础组件初始化。

初始化完毕后进行主协程（main goroutine）的运行，并放入等待队列（GMP 模型），最后调度器开始进行循环调度。

### 小结

根据上述源码剖析，可以得出如下 Go 应用程序引导的流程图：

![Go 程序引导过程](https://image.eddycjy.com/057c1ccb06c16e8c5f38ff5800e3fa63.jpg)

在 Go 语言中，实际的运行入口并不是用户日常所写的 `main func`，更不是 `runtime.main` 方法，而是从 `rt0_*_amd64.s` 开始，最终再一路 JMP 到 `runtime·rt0_go` 里去，再在该方法里完成一系列 Go 自身所需要完成的绝大部分初始化动作。

其中整体包括：
- 运行时类型检查、系统参数传递、CPU 核数获取及设置、运行时组件的初始化（调度器、内存分配器、堆、栈、GC 等）。
- 运行 main goroutine。
- 运行相应的 GMP 等大量缺省行为。
- 涉及到调度器相关的大量知识。

后续将会继续剖析将进一步剖析 `runtime·rt0_go` 里的爱与恨，尤其像是 `runtime.main`、`runtime.schedinit` 等调度方法，都有非常大的学习价值，有兴趣的小伙伴可以持续关注。

## Go 调度器初始化

知道了 Go 程序是怎么引导起来的之后，我们需要了解 Go Runtime 中调度器是怎么流转的。

### runtime.mstart

这里主要关注 `runtime.mstart` 方法：

```golang
func mstart() {
	// 获取 g0
	_g_ := getg()

	// 确定栈边界
	osStack := _g_.stack.lo == 0
	if osStack {
		size := _g_.stack.hi
		if size == 0 {
			size = 8192 * sys.StackGuardMultiplier
		}
		_g_.stack.hi = uintptr(noescape(unsafe.Pointer(&size)))
		_g_.stack.lo = _g_.stack.hi - size + 1024
	}
	_g_.stackguard0 = _g_.stack.lo + _StackGuard
	_g_.stackguard1 = _g_.stackguard0
  
  // 启动 m，进行调度器循环调度
	mstart1()

	// 退出线程
	if mStackIsSystemAllocated() {
		osStack = true
	}
	mexit(osStack)
}
```

- 调用 `getg` 方法获取 GMP 模型中的 g，此处获取的是 g0。
- 通过检查 g 的执行栈 `_g_.stack` 的边界（堆栈的边界正好是 lo, hi）来确定是否为系统栈。若是，则根据系统栈初始化 g 执行栈的边界。
- 调用 `mstart1` 方法启动系统线程 m，进行调度器循环调度。
- 调用 `mexit` 方法退出系统线程 m。

### runtime.mstart1

这么看来其实质逻辑在 `mstart1` 方法，我们继续往下剖析：

```golang
func mstart1() {
	// 获取 g，并判断是否为 g0
	_g_ := getg()
	if _g_ != _g_.m.g0 {
		throw("bad runtime·mstart")
	}

	// 初始化 m 并记录调用方 pc、sp
	save(getcallerpc(), getcallersp())
	asminit()
	minit()

	// 设置信号 handler
	if _g_.m == &m0 {
		mstartm0()
	}
	// 运行启动函数
	if fn := _g_.m.mstartfn; fn != nil {
		fn()
	}

	if _g_.m != &m0 {
		acquirep(_g_.m.nextp.ptr())
		_g_.m.nextp = 0
	}
	schedule()
}
```

- 调用 `getg` 方法获取 g。并且通过前面绑定的 `_g_.m.g0` 判断所获取的 g 是否 g0。若不是，则直接抛出致命错误。因为调度器仅在 g0 上运行。
- 调用 `minit` 方法初始化 m，并记录调用方的 PC、SP，便于后续 schedule 阶段时的复用。
- 若确定当前的 g 所绑定的 m 是 m0，则调用 `mstartm0` 方法，设置信号 handler。该动作必须在 `minit` 方法之后，这样 `minit` 方法可以提前准备好线程，以便能够处理信号。
- 若当前 g 所绑定的 m 有启动函数，则运行。否则跳过。
- 若当前 g 所绑定的 m 不是 m0，则需要调用 `acquirep` 方法获取并绑定 p，也就是 m 与 p 绑定。
- 调用 `schedule` 方法进行正式调度。

忙活了一大圈，终于进入到开题的主菜了，原来潜伏的很深的 `schedule` 方法才是真正做调度的方法，其他都是前置处理和准备数据。

由于篇幅问题，`schedule` 方法会放到下篇再继续剖析，我们先聚焦本篇的一些细节点。

## 问题深剖

不过到这里篇幅也已经比较长了，积累了不少问题。我们针对在 Runtime 中出镜率最高的两个元素进行剖析：
1. `m0` 是什么，作用是？
2. `g0` 是什么，作用是？

### m0

m0 是 Go Runtime 所创建的第一个系统线程，一个 Go 进程只有一个 m0，也叫主线程。

从多个方面来看：
- 数据结构：m0 和其他创建的 m 没有任何区别。
- 创建过程：m0 是进程在启动时应该汇编直接复制给 m0 的，其他后续的 m 则都是 Go Runtime 内自行创建的。
- 变量声明：m0 和常规 m 一样，m0 的定义就是 `var m0 m`，没什么特别之处。

### g0

g 一般分为三种，分别是：
- 执行用户任务的叫做 g。
- 执行 `runtime.main` 的 main goroutine。
- 执行调度任务的叫 g0。。

g0 比较特殊，每一个 m 都只有一个 g0（仅此只有一个 g0），且每个 m 都只会绑定一个 g0。在 g0 的赋值上也是通过汇编赋值的，其余后续所创建的都是常规的 g。

从多个方面来看：
- 数据结构：g0 和其他创建的 g 在数据结构上是一样的，但是存在栈的差别。在 g0 上的栈分配的是系统栈，在 Linux 上栈大小默认固定 8MB，不能扩缩容。 而常规的 g 起始只有 2KB，可扩容。
- 运行状态：g0 和常规的 g 不一样，没有那么多种运行状态，也不会被调度程序抢占，调度本身就是在 g0 上运行的。
- 变量声明：g0 和常规 g，g0 的定义就是 `var g0 g`，没什么特别之处。

### 小结

在本章节中我们讲解了 Go 调度器初始化的一个过程，分别涉及：
- runtime.mstart。
- runtime.mstart1。

基于此也了解到了在调度器初始化过程中，需要准备什么，初始化什么。另外针对调度过程中最常提到的 m0、g0 的概念我们进行了梳理和说明。

## 总结

在今天这篇文章中，我们详细的介绍了 Go 语言的引导启动过程中的所有流程和初始化动作。

同时针对调度器的初始化进行了初步分析，详细介绍了 m0、g0 的用途和区别。
在下一篇文章中我们将进一步对真正调度的 `schedule` 方法进行详解，这块也是个硬骨头了。

================================================
FILE: content/posts/go/go-concurrent-lock.md
================================================
---
title: "Go 并发：一些有趣的现象和要避开的 “坑”"
date: 2020-12-10T00:25:59+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

最近在看 Go 并发相关的内容，发现还是有不少细节容易让人迷迷糊糊的，一个不小心就踏入深坑里，且指不定要在上线跑了一些数据后才能发现，那可真是太人崩溃了。

今天来分享几个案例，希望大家在编码时能够避开这几个 “坑”。

## 案例一

### 演示代码

第一个案例来自 @鸟窝 大佬在极客时间的分享，代码如下：

```
func main() {
	count := 0
	wg := sync.WaitGroup{}
	wg.Add(10)
	for i := 0; i < 10; i++ {
		go func() {
			defer wg.Done()
			for j := 0; j < 100000; j++ {
				count++
			}
		}()
	}
	wg.Wait()

	fmt.Println(count)
}
```

思考一下，最后输出的 `count` 变量的值是多少？是不是一百万？

### 输出结果

在上述代码中，我们通过 `for-loop ` 循环起 `goroutine` 进行自增，并使用了 `sync.WaitGroup` 来保证所有的 goroutine 都执行完毕才输出最终的结果值。

最终的输出结果如下：

```
// 第一次执行
638853

// 第二次执行
654473

// 第三次执行
786193
```

输出的结果值不是恒定的，也就是每次输出的都不一样，且基本不会达到想象中的一百万。

### 分析原因

其原因在于 `count++` 并不是一个原子操作，在汇编上就包含了好几个动作，如下：

```
MOVQ "".count(SB), AX 
LEAQ 1(AX), CX 
MOVQ CX, "".count(SB)
```

因为可能会同时存在多个 goroutine 同时读取到 `count` 的值为 1212，并各自自增 1，再将其写回。

与此同时也会有其他的 goroutine 可能也在其自增时读到了值，形成了互相覆盖的情况，这是一种并发访问共享数据的错误。

### 发现问题

这类竞争问题可以通过 Go 语言所提供的的 race 检测（[Go race detector](https://blog.golang.org/race-detector)）来进行分析和发现：

```
$ go run -race main.go 
==================
WARNING: DATA RACE
Read at 0x00c0000c6008 by goroutine 13:
  main.main.func1()
      /Users/eddycjy/go-application/awesomeProject/main.go:28 +0x78

Previous write at 0x00c0000c6008 by goroutine 7:
  main.main.func1()
      /Users/eddycjy/go-application/awesomeProject/main.go:28 +0x91

Goroutine 13 (running) created at:
  main.main()
      /Users/eddycjy/go-application/awesomeProject/main.go:25 +0xe4

Goroutine 7 (running) created at:
  main.main()
      /Users/eddycjy/go-application/awesomeProject/main.go:25 +0xe4
==================
...
489194
Found 3 data race(s)
exit status 66
```

编译器会通过探测所有的内存访问，监听其内存地址的访问（读或写）。在应用运行时就能够发现对共享变量的访问和操作，进而发现问题并打印出相关的警告信息。

需要注意的一点是，`go run -race` 是运行时检测，并不是编译时。且 race 存在明确的性能开销，通常是正常程序的十倍，因此不要想不开在生产环境打开这个配置，很容易翻车。

## 案例二

### 演示代码

第二个案例来自煎鱼在脑子的分享，代码如下：

```
func main() {
	wg := sync.WaitGroup{}
	wg.Add(5)
	for i := 0; i < 5; i++ {
		go func(i int) {
			defer wg.Done()
			fmt.Println(i)
		}(i)
	}
	wg.Wait()
}
```

思考一下，最后输出的结果是什么？值都是 4 吗？输出是稳定有序的吗？

### 输出结果

在上述代码中，我们通过 `for-loop` 循环起了多个 `goroutine`，并将变量 `i` 作为形参传递给了 `goroutine`，最后在 `goroutine` 内输出了变量 `i`。

最终的输出结果如下：

```
// 第一次输出
0
1
2
4
3

// 第二次输出
4
0
1
2
3
```

显然，从结果上来看，输出的值都是无序且不稳定的，值更不是 4。这到底是为什么？

### 分析原因

其原因在于，即使所有的 `goroutine` 都创建完了，但 `goroutine` 不一定已经开始运行了。

也就是等到 `goroutine` 真正去执行输出时，变量 `i` （值拷贝）可能已经不是创建时的值了。

其整个程序扭转实质上分为了多个阶段，也就是各自运行的时间线并不同，可以其拆分为：

- 先创建：`for-loop` 循环创建 `goroutine`。

- 再调度：协程`goroutine` 开始调度执行。

- 才执行：开始执行 `goroutine` 内的输出。

同时 `goroutine` 的调度存在一定的随机性（建议了解一下 GMP 模型），那么其输出的结果就势必是无序且不稳定的。

### 发现问题

这时候你可能会想，那前面提到的 `go run -race` 能不能发现这个问题呢。如下：

```
$ go run -race main.go
0
1
2
3
4
```

没有出现警告，显然是不能的，因为其本质上并不是并发访问共享数据的错误，且会导致程序变成了串行，从而蒙蔽了你的双眼。

## 案例三

### 演示代码

第三个案例来自煎鱼在梦里的分享，代码如下：

```
func main() {
	wg := sync.WaitGroup{}
	wg.Add(5)
	for i := 0; i < 5; i++ {
		go func() {
			defer wg.Done()
			fmt.Println(i)
		}()
	}
	wg.Wait()
}
```

思考一下，最后输出的结果是什么？值都是 4 吗？会像案例二一样乱窜吗？

### 输出结果

在上述代码中，与案例二大体没有区别，主要是变量 `i` 没有作为形参传入。

最终的输出结果如下：

```
// 第一次输出
5
5
5
5
5
```

初步从输出的结果上来看都是 5，这时候就会有人迷糊了，为什么不是 4 呢？

不少人会因不是 4 而陷入了迷惑，但千万不要被一两次的输出迷惑了心智，认为铁定就是 5 了。可以再动手多输出几次，如下：

```
// 多输出几次
5
3
5
5
5
```

最终会发现...输出结果存在随机性，输出结果并不是 100% 都是 5，更不用提 4 了。这到底是为什么呢？

### 分析原因

其原因与案例二其实非常接近，理论上理解了案例二也就能解决案例三。

其本质还是创建 `goroutine` 与真正执行 `fmt.Println` 并不同步。因此很有可能在你执行 `fmt.Println` 时，循环 `for-loop` 已经运行完毕，因此变量 `i` 的值最终变成了 5。

那么相反，其也有可能没运行完，存在随机性。写个 test case 就能发现明显的不同。

## 总结

在本文中，我分享了几个近期看到次数最频繁的一些并发上的小 “坑”，希望对你有所帮助。同时你也可以回想一下，在你编写 Go 并发程序有没有也遇到过什么问题？

同时你也可以回想一下，在你编写 Go 并发程序有没有也遇到过什么问题？

欢迎大家一起讨论交流。

================================================
FILE: content/posts/go/go-design.md
================================================
---
title: "上帝视角：Go 语言设计失误，缺乏远见？"
date: 2021-12-31T12:55:13+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间我有一个朋友在某乎上摸鱼时，给我甩来一个主题为《golang 设计者是如何偿还技术债的》链接。

说是让我学习、围观一下社区观点，早日好修成正果，本鱼表示满脸问号。

原回答如下图：

![](https://files.mdnice.com/user/3610/4bbdfe91-b98e-4ae1-bcc6-aa5fc50cd184.png)

主要是以极短的话语表述 Go 语言的 “泛型、异常、channel、annotation、模块依赖” 的设计是失误的。

说是没有向各种编程语言的 “最佳实践” 各取所需。

## 那些故事

刚好煎鱼也入门 Go 没几天，偶尔翻过 issues 和 proposal，看了一点点历史事件。

![图来自 Introduction to Golang](https://files.mdnice.com/user/3610/3213b564-1a53-4dcf-9b69-4f4359bd50db.png)

也从我的观点来围观一下 Go 官方这些年为特性挣扎过的那些事。

涉及：
1. 泛型。
2. 错误处理。
3. 依赖管理。
4. 注解。

### 泛型

**为什么 Go 语言这么久都没有泛型**，是不是 Go 官方不够 “聪明”，抄作业都不会抄。这显然是不对的。

有如下几点原因：
1. 泛型本质上并不是绝对的必需品。
2. 泛型不是 Go 语言的早期目标。
3. 其他 feature 更重要，把精力放在这些上面，Go 团队人力很有限的。

#### 历史尝试

在以往的尝试中，Go 团队有人进行过不少的泛型 proposal 试验。基本时间线（via @changkun）如下：

|  简述   | 时间  | 作者 |
|  ----  | ----  | --- |
| Type Functions  | 2010年 | Ian Lance Taylor |
| Generalized Types  | 2011年 | Ian Lance Taylor |
| Generalized Types v2  | 2013年 | Ian Lance Taylor |
| Type Parameters  | 2013年 | Ian Lance Taylor |
| go:generate  | 2014年 | Rob Pike |
| First Class Types  | 2015年 | Bryan C.Mills |
| Contracts  | 2018年 | Ian Lance Taylor, Robert Griesemer |
| Contracts  | 2019年 | Ian Lance Taylor, Robert Griesemer  |
| Redundancy in Contracts(2019)'s Design  | 2019年 | Ian Lance Taylor, Robert Griesemer |
| Constrained Type Parameters(2020, v1)  | 2020年 | Ian Lance Taylor, Robert Griesemer |
| Constrained Type Parameters(2020, v2)  | 2020年 | Ian Lance Taylor, Robert Griesemer |
| Constrained Type Parameters(2020, v3)  | 2020年 | Ian Lance Taylor, Robert Griesemer |

我们观察一下，10 年过去了，Ian Lance Taylor 依然在开展泛型提案，持续地在思考着 Go 泛型。

坚持思考，这一点值得我们学习。

对 Go 泛型历史有兴趣的读者可以看看《[为什么 Go 的泛型一拖再拖？](https://mp.weixin.qq.com/s/ftmuA9g7QPAwSwiswRuSuw)》，给了明确完整的内容介绍和过程描述了。

### 下一步计划

在 2021 年尾巴的我们，明年（2022年） **Go1.18 左右就可以见到 Go 泛型，基本跑不了。**

想想就激动，如下图（此刻是 4 个月后）：

![图来自网上](https://files.mdnice.com/user/3610/934613fa-2564-4f26-bd40-bb309bd48dcf.png)

在出来前可以看看《[Go 1.17 支持泛型了？具体怎么用](https://mp.weixin.qq.com/s/Pf7YuFpwbldSB60DDCBtlA)》，可以作为玩具用了。

接下来可以预见泛型出来后，一堆工具库和数据结构很大可能会被逐步改写，像是《[Go 提案：增加泛型版 slices 和 maps 新包](https://mp.weixin.qq.com/s/D7u7nxixctoFIL-Pch0zvw)》，早已摩拳擦掌。

届时 Go 源码类别的书的部分内容也会失时效，需要关注 Go 版本的时效性。

### 错误处理

在日常工程中，我们写的、看到最多的可能就是这一段标志性 Go 代码：

```golang
func main() {
 x, err := foo()
 if err != nil {
   // handle error
 }
 y, err := foo()
 if err != nil {
   // handle error
 }
 z, err := foo()
 if err != nil {
   // handle error
 }
 s, err := foo()
 if err != nil {
   // handle error
 }
}
```

这是在业内被吐槽的最多的，甚至都可以用来作为 Gopher 的互认。

#### 设计方向

那 Go 是瞎设计的吗，就粗制滥造，搞个错误 err 的返回约定惯例。像是：

```golang
func foo() err {
    return nil
}
```

其实并不是，Go 团队在设计上有意识地选择了**显式**的设计方向，如下：
- 使用显式错误结果。
- 使用显式错误检查。

这和其他语言不一样 ，是由于 Go 团队也认识到了异常处理的不可见错误检查所带来的问题。

设计草案有一部分是受到了这些问题的启发。如下：

![](https://files.mdnice.com/user/3610/9c308232-631e-4aa3-b265-85daf2b9909d.png)

目前 Go 官方也没有打算去掉 “显式” 这一做法，新版 Go2 错误处理的核心目标是：“**错误检查更加轻便，减少专门用于错误检查的 Go 程序代码的数量和所花费的时间**。”。

从 Go2 的趋势来看，主要是增加关键字和修饰来解决这个问题，相当于是堆积木了，而不是直接把他干掉的。

这在 Go 核心团队内是非常明确的。

#### 进一步深入

对 Go 语言错误处理还想进一步深入的，推荐看下面这几篇文章：

- 《[先睹为快，Go2 Error 的挣扎之路](https://mp.weixin.qq.com/s/XILveKzh07BOQnqxYDKQsA)》
- 《[Go errors 不会有进一步的改进计划](https://mp.weixin.qq.com/s/ixBMcAgqW51I0r_hkw5l5A)》
- 《[你对 Go 错误处理的 4 个误解！](https://mp.weixin.qq.com/s/Ey-yqIq__wpaLTlBAOHjxg)》

### 依赖管理

Go 语言在一开始是完全基于 GOPATH 作为依赖管理的模式，当时也闹了不少的争议出来。有以下核心问题：
1. 依赖要手动拉取和下载，没有强版本化的概念，开发者很难受（例如：不兼容升级、要拉取同一份）。
2. 依赖和工程代码必须在 GOPATH 下才能运行，不能任意摆放。

所以在 Go1.0~Go1.11 中，各路神仙发招，社区出现了各种诸如 dep、glide、godep 等依赖包管理工具。

#### 时间线

后续 Go 团队在 Russ Cox 的强势推进下，力排众议，推动 Go modules 的发展：

![](https://files.mdnice.com/user/3610/66291d6e-b10b-42db-9242-d5e16eb94237.png)

时间线如下：
- Go1.11 起开始推进 Go modules（前身 vgo）。
- Go1.13 起不再推荐使用 GOPATH 的使用模式。
- Go1.14 表示已经准备好，可以用在生产上（ready for production）了。

#### 为什么这么晚

为什么 Go modules 这么晚才诞生，这是不是就是 Go 团队的设计失误呢？

我认为，是也不是。

Go 的诞生一开始是为了解决 Google 几位大佬自己的痛点。

在 Google 的依赖管理上，本身是大仓库（Monorepo）的模式，企业内部有自己一整套工具和流程，设计之初没有这块的强诉求。

如下：

![图来自 Mono Repo vs Multi Repo](https://files.mdnice.com/user/3610/c589a0af-e0c1-4e9b-83c2-899369c9fa8e.jpg)

有兴趣的读者详细可阅读《[Why Google Stores Billions of Lines of Code in a Single Repository](https://dl.acm.org/doi/epdf/10.1145/2854146)》，

Go 在社区开源后，大规模使用后这个问题就爆发了，社区自行释出了方案。可惜，五花八门，也都没有解决好。官方队伍就自己上手了。

要知道，没有技术方案是完美的。Go modules 也被不少人所吐槽，存在争议。

#### 进一步深入

想更进一步深入 Go modules 的小伙伴，可以看看下述文章：
- 《[Go Modules 终极入门和历史](https://mp.weixin.qq.com/s/6gJkSyGAFR0v6kow2uVklA)》
- 《[干货满满的 Go Modules 和 goproxy.cn](https://mp.weixin.qq.com/s/jpp7vs3Fdg4m15P1SHt1yA)》

### 注解

Go 开发者中有大部分同学都有其他语言的使用经验。在其他语言中，注解是一个强大的工具，没得用会很不习惯。

![图片来自网络](https://files.mdnice.com/user/3610/9061ff09-9776-4a74-9550-fc5a4f17f824.png)

甚至有听过没有注解，就自嘲不会 “写” 代码了，所以一上来就找 Go 语言的注解怎么用了。

#### 一些疑惑

我有一个朋友，经常会听到如下疑惑，甚至无奈的发问：

- “怎么样在函数前声明，直接开启事务？”
- "为什么 Java 可以完美注解，Go 就不行，难以理解，我无法接受..."
- “那 Go 支持什么程度的注解？”

Go 的 “注解” 支撑的非常有限，基本都是 `//go build`、`go:generate` 这类辅助，达不到标准的装饰器的作用。

#### 为什么不支持

没有全面的支持注解来做装饰器，显然不算 Go 的设计失误，这是刻意为之，这是与错误处理的设计理念相关联。

Go issues 上有人提过类似的提案：

![](https://files.mdnice.com/user/3610/9695f163-65e8-456a-8dce-bb8551739016.png)

Go Contributor @ianlancetaylor 给出了明确的答复，Go在设计上更倾向于明确的、显式的编程风格。

优缺点如下：
- 优势：不知道 Go 能从添加装饰器中得到什么好处，没能在 issues 上明确论证。
- 缺点：是明确的，会存在意外设置的情况。

因如下原因，没有接受注解：
- 对比现有代码方法，这种装饰器的新的方法没有提供比现有方法更多的优势，大到足矣推翻原有的设计思路。
- 社区内的投票，支持的也很少（基于表情符号的投票），用户反馈不多。

可能有小伙伴会说了，有注解做装饰器了，代码会简洁不少。

但其实 Go 团队的态度很明确：

![](https://files.mdnice.com/user/3610/bb357e12-9b15-4729-9381-977d164b6b04.png)

Go 认为**可读性更重要**，如果只是额外多写一点代码，在权衡后，还是可以接受的。

如果想自己在 Go 中实现完整注解的，可以详细阅读《[Go：我有注解，Java：不，你没有！](https://mp.weixin.qq.com/s/hrsagmDtjt6r9fJKf8SUcQ)》，可以给到你一些思路。

## 偿还的过程

如果是在职场中工作多年的小伙伴，其实不难发现 Go 的发展史和业务的发展节奏是类似的。

在社区中吐槽的主要是两块，如下：
- 为什么这个功能不如此设计？
- 这个功能为什么没有支持？

### 不如此设计

为什么 Go 语言不如此设计？经典的像是 Go 的错误处理（error），很多小伙伴会**先入为主**，以其他语言的最佳实践，要教 Go 团队设计，要 throw，要 catch！

其实想一下，我们做一个业务，这个业务就是 Go 语言。我们需要先做业务建模，确定 Go 的核心思想，才能持续的迭代和设计。

Go 语言的设计定义很明显是：**既要简单、还要显式，不能有隐式、要避免复杂**，所以社区传递的是 “**less is more**” 的设计理念。

这么想，很多提案的落地，被拒等，都能了解到 Go 语言的设计哲学和团队理念。

### 还没有支持

为什么 Go 语言的 XXX 功能没有支持？经典的像是 Go 的泛型、注解等功能。

还没有支持的可能性有三点，如下：
1. 还没有想清楚。
2. 早就被拒绝了。
3. 优先级不够高。

实际上和我们业务迭代一样，Go 团队的人力资源有限，**做事会有优先级**。前文所提到的 Russ Cox 就是现在 Go 团队 Leader，每年也会开相关的会议讨论事项。

像是 Go 泛型，显然没有，也不会影响到 Go 在业务初期的短期发展，国内依然存有一定的占用率。2011 年没有想清楚，也就一直持续思考和尝试了...

而注解，或是你们想到的。很多在 go issues 其实早就被拒绝过多次，自然还没有支持，也是因为他不大可能直接出现了。

### 推进的模式

Go 在推进或偿还新技术改进时，现在采取的模式都是一样的。会先设计一个编译时可以指定的 “变量”。

例如：
- 泛型的 G 变量。
- Modules 的 GO111MODULE 变量。

再在 Go 的不断迭代中，推进使用和反馈，再推进变量的默认开启，逐渐去除。

可以参考 GO111MODULE 的过程。

## 总结

我们在学习很多语言、技能时，会以既有的知识去认知，再对新的对象建立新的认知树，很容易会有**先入为主的认知行为**。

但若没有及时思考，就很容易产生偏见。**认为 XXX 是 XXX，你 Go 语言就应该是 XXX，这样是有失偏颇的**。

就像我们行业经常讨论的，网上的 A 同学，35 岁被裁员了。那你我，35 岁就 100% 会下岗吗？

相反，Go 语言这 10+ 年来，基于自己的设计理念。保持了大致一贯的 less is more 设计理念，是值得赞许的。

我们要知道软件设计，是**没有银弹**的。Go 语言的设计理念，有好有坏，**社区也有不少人对大道至简的理念嗤之以鼻**。

**你又是怎么看待 Go 语言的呢**，欢迎点赞、留言，一起来交流和讨论：）

================================================
FILE: content/posts/go/go-empty-struct.md
================================================
---
title: "用 Go struct 不能犯的一个低级错误！"
date: 2021-06-17T12:44:27+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间我分享了 《手撕 Go 面试官：Go 结构体是否可以比较，为什么？》的文章，把基本 Go struct 的比较依据研究了一番。这不，最近有一位读者，遇到了一个关于 struct 的新问题，不得解。

大家一起来看看，建议大家在看到代码例子后先思考一下答案，再往下看。

独立思考很重要。

## 疑惑的例子

其给出的例子一如下：

```golang
type People struct {}

func main() {
 a := &People{}
 b := &People{}
 fmt.Println(a == b)
}
```

你认为输出结果是什么呢？

输出结果是：false。

再稍加改造一下，例子二如下：

```golang
type People struct {}

func main() {
 a := &People{}
 b := &People{}
 fmt.Printf("%p\n", a)
 fmt.Printf("%p\n", b)
 fmt.Println(a == b)
}
```
输出结果是：true。

他的问题是 "**为什么第一个返回 false 第二个返回 true，是什么原因导致的**？

煎鱼进一步的精简这个例子，得到最小示例：

```golang
func main() {
	a := new(struct{})
	b := new(struct{})
	println(a, b, a == b)

	c := new(struct{})
	d := new(struct{})
	fmt.Println(c, d)
	println(c, d, c == d)
}
```

输出结果：

```bash
// a, b; a == b
0xc00005cf57 0xc00005cf57 false

// c, d
&{} &{}
// c, d, c == d
0x118c370 0x118c370 true
```

第一段代码的结果是 false，第二段的结果是 true，且可以看到内存地址指向的完全一样，也就是排除了输出后变量内存指向改变导致的原因。

进一步来看，似乎是 `fmt.Print` 方法导致的，但一个标准库里的输出方法，会导致这种奇怪的问题？

## 问题剖析

如果之前有被这个 “坑” 过，或有看过源码的同学。可能能够快速的意识到，导致这个输出是**逃逸分析**所致的结果。

我们对例子进行逃逸分析：

```
// 源代码结构
$ cat -n main.go
     5	func main() {
     6		a := new(struct{})
     7		b := new(struct{})
     8		println(a, b, a == b)
     9	
    10		c := new(struct{})
    11		d := new(struct{})
    12		fmt.Println(c, d)
    13		println(c, d, c == d)
    14	}

// 进行逃逸分析
$ go run -gcflags="-m -l" main.go
# command-line-arguments
./main.go:6:10: a does not escape
./main.go:7:10: b does not escape
./main.go:10:10: c escapes to heap
./main.go:11:10: d escapes to heap
./main.go:12:13: ... argument does not escape
```

通过分析可得知变量 a, b 均是分配在栈中，而变量 c, d 分配在堆中。

其关键原因是因为调用了 `fmt.Println` 方法，该方法内部是涉及到大量的反射相关方法的调用，会造成逃逸行为，也就是分配到堆上。

### 为什么逃逸后相等

关注第一个细节，就是 “为什么逃逸后，两个空 struct 会是相等的？”。

这里主要与 Go runtime 的一个优化细节有关，如下：

```golang
// runtime/malloc.go
var zerobase uintptr
```

变量 `zerobase` 是所有 0 字节分配的基础地址。更进一步来讲，就是空（0字节）的在进行了逃逸分析后，往堆分配的都会指向 `zerobase` 这一个地址。

所以空 struct 在逃逸后本质上指向了 `zerobase`，其两者比较就是相等的，返回了 true。

### 为什么没逃逸不相等

关注第二个细节，就是 “为什么没逃逸前，两个空 struct 比较不相等？”。

![Go spec](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/dc05fb027a9a481f83053f08b1ee2868~tplv-k3u1fbpfcp-zoom-1.image)

从 Go spec 来看，这是 Go 团队刻意而为之的设计，不希望大家依赖这一个来做判断依据。如下：

>> This is an intentional language choice to give implementations flexibility in how they handle pointers to zero-sized objects. If every pointer to a zero-sized object were required to be different, then each allocation of a zero-sized object would have to allocate at least one byte. If every pointer to a zero-sized object were required to be the same, it would be different to handle taking the address of a zero-sized field within a larger struct.

还说了一句很经典的，细品：

>> Pointers to distinct zero-size variables may or may not be equal.

另外空 struct 在实际使用中的场景是比较少的，常见的是：
- 设置 context，传递时作为 key 时用到。
- 设置空 struct 业务场景中临时用到。

但业务场景的情况下，也大多数会随着业务发展而不断改变，假设有个远古时代的 Go 代码，依赖了空 struct 的直接判断，岂不是事故上身？

#### 不可直接依赖 

因此 Go 团队这番操作，与 Go map 的随机性如出一辙，避免大家对这类逻辑的直接依赖，是值得思考的。

而在没逃逸的场景下，两个空 struct 的比较动作，你以为是真的在比较。实际上已经在代码优化阶段被直接优化掉，转为了 false。

因此，虽然在代码上看上去是 == 在做比较，实际上结果是 a == b 时就直接转为了 false，比都不需要比了。

你说妙不？

#### 没逃逸让他相等

既然我们知道了他是在代码优化阶段被优化的，那么相对的，知道了原理的我们也可以借助在 go 编译运行时的 gcflags 指令，让他不优化。

在运行前面的例子时，执行 `-gcflags="-N -l"` 指令：

```
$ go run -gcflags="-N -l" main.go 
0xc000092f06 0xc000092f06 true
&{} &{}
0x118c370 0x118c370 true
```

你看，两个比较的结果都是 true 了。

## 总结

在今天这篇文章中，我们针对 Go 语言中的空结构体（struct）的比较场景进行了进一步的补全。经过这两篇文章的洗礼，你会更好的理解 Go 结构体为什么叫既可比较又不可比较了。

而空结构比较的奇妙，主要原因如下：
- 若逃逸到堆上，空结构体则默认分配的是 `runtime.zerobase` 变量，是专门用于分配到堆上的 0 字节基础地址。因此两个空结构体，都是 `runtime.zerobase`，一比较当然就是 true 了。
- 若没有发生逃逸，也就分配到栈上。在 Go 编译器的代码优化阶段，会对其进行优化，直接返回 false。并不是传统意义上的，真的去比较了。

不会有人拿来出面试题，不会吧，为什么 Go 结构体说可比较又不可比较？

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，回复【**000**】有我准备的一线大厂面试算法题解和资料；本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，欢迎 Star 催更。

## 参考

- 欧神的微信交流
- 曹大的一个空 struct 的“坑”



================================================
FILE: content/posts/go/go-error2panic.md
================================================
---
title: "Go 错误处理：用 panic 取代 err != nil 的模式"
date: 2020-12-12T17:21:42+08:00
toc: true
images:
tags: 
  - go
---

前段时间我分享了文章 《先睹为快，Go2 Error 的挣扎之路》后，和一位朋友进行了一次深度交流，他给我分享了他们项目组对于 Go 错误处理的方式调整。

简单来讲，就是在业务代码中使用 `panic` 的方式来替代 “永无止境” 的 `if err != nil`。这就是今天本文的重点内容，我们一起来看看是怎么做，又有什么优缺点。

## 为什么想替换

在 Go 语言中 `if err != nil` 写的太多，还要管方法声明各种，嫌麻烦又不方便：

```
err := foo()
if err != nil {
     //do something..
     return err
}

err := foo()
if err != nil {
     //do something..
     return err
}

err := foo()
if err != nil {
     //do something..
     return err
}

err := foo()
if err != nil {
     //do something..
     return err
}
```

上述还是示例代码，比较直面。若是在工程实践，还得各种 package 跳来跳去加 `if err != nil`，总的来讲比较繁琐，要去关心整体的上下游。更具体的就不赘述了，可以翻看我先前的文章。

## 怎么替换 err != nil

不想写 `if err != nil` 的代码，方式之一就是用 `panic` 来替代他。示例代码如下：

```
func GetFish(db *sql.DB, name string) []string {
	rows, err := db.Query("select name from users where `name` = ?", name)
	if err != nil {
		panic(err)
	}
	defer rows.Close()

	var names []string
	for rows.Next() {
		var name string
		err := rows.Scan(&name)
		if err != nil {
			panic(err)
		}

		names = append(names, name)
	}

	err = rows.Err()
	if err != nil {
		panic(err)
	}

	return names
}
``` 

在上述业务代码中，我们通过 `panic` 的方式取代了 `return err` 的函数返回，自然其所关联的下游业务代码也就不需要编写 `if err != nil` 的代码：

```
func main() {
	fish1 := GetFish(db, "煎鱼")
	fish2 := GetFish(db, "咸鱼")
	fish3 := GetFish(db, "摸鱼")
	...
}
```

同时在转换为使用 `panic` 模式的错误机制后，我们必须要在外层增加 `recover` 方法：

```
func AppRecovery() gin.HandlerFunc {
	return func(c *gin.Context) {
		defer func() {
			if err := recover(); err != nil {
				if _, ok := err.(AppErr); ok {
					// do something...
				} else {
					panic(err)
				}
			}
		}()
	}
}
```

每次 `panic` 后根据其抛出的错误进行断言，识别是否定制的 `AppErr` 错误类型，若是则可以进行一系列的处理动作。否则可继续向上 `panic` 抛出给顶级的 `Recovery` 方法进行处理。

这就是一个相对完整的 `panic` 错误链路处理了。

## 优缺点

- 从优点上来讲：

    - 整体代码结构看起来更加的简洁，仅专注于实现逻辑即可。

    - 不需要关注和编写冗杂的 `if err != nil` 的错误处理代码。

- 从缺点上来讲：

    - 认知负担的增加，需要参加项目的每一个新老同学都清楚该模式，要做一个基本规范或培训。

    - 存在一定的性能开销，每次 `panic` 都存在用户态的上下文切换。

    - 存在一定的风险性，一旦 `panic` 没有 `recover` 住，就会导致事故。

    - Go 官方并不推荐，与 `panic` 本身的定义相违背，也就是 `panic` 与 `error` 的概念混淆。

## 总结

在今天这篇文章给大家分享了如何使用 `panic` 的方式来处理 Go 的错误，其必然有利必有有弊，需要做一个权衡了。

你们团队有没有为了 Go 错误处理做过什么新的调整呢？欢迎在留言区交流和分享。

================================================
FILE: content/posts/go/go-errors-boom.md
================================================
---
title: "生产环境遇到一个 Go 问题，整组人都懵逼了..."
date: 2021-07-07T12:43:49+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间正在疯狂写代码的时候，突然有一个读者给我提了一个问题，让我有了一定的兴趣：

![image.png](https://p6-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/c1011e66fe104d228dcaa2083b554fc8~tplv-k3u1fbpfcp-watermark.image)

我还是比较感兴趣的，因为是生产环境、有代码，且整组人都懵逼的问题。

在征求了小伙伴的意见后，今天分享出来，大家也思考一下原因，一起规避这个 “坑”。

## 案例一

代码示例如下：

```golang
type MyErr struct {
    Msg string
}

func main() {
    var e error
    e = GetErr()
    log.Println(e == nil)
}

func GetErr() *MyErr {
    return nil
}

func (m *MyErr) Error() string {
    return "脑子进煎鱼了"
}
```

请思考一下，**这段程序的输出结果是什么**？

该程序所调用的 `GetErr` 方法所返回的是 `nil`，而外部判断是 `e == nil`，因此最终的输出结果是 true，对吗？ 

输出结果如下：

```
2021/04/04 08:39:04 false
```

答案是：false。

## 案例二

代码示例如下：

```golang
type Base interface {
    do()
}

type App struct {
}

func main() {
    var base Base
    base = GetApp()
    
    log.Println(base)
    log.Println(base == nil)
}

func GetApp() *App {
    return nil
}
func (a *App) do() {}
```

请思考一下，**这段程序的输出结果是什么**？

该程序调用了 `GetApp` 方法，该方法返回的是 `nil`，因此其赋值的 `base` 也是 `nil`。因此判断 `base == nil` 的最终输出结果是 `<nil>` 和 `true`，对吗？

输出结果如下：

```
2021/04/04 08:59:00 <nil>
2021/04/04 08:59:00 false
```

答案是：`<nil>` 和 false。

## 为什么

为什么，这两段 Go 程序是怎么回事...也太反直觉了？其背后的原因本质上还是对 Go 语言中 interface 的基本原理的理解。

在案例一中，虽然 `GetErr` 方法确实是返回了 `nil`，返回的类型也是具体的 `*MyErr` 类型。但是其接收的变量却不是具体的结构类型，而是 `error` 类型：

```golang
var e error
e = GetErr()
```

在 Go 语言中， `error` 类型本质上是 interface：

```golang
type error interface {
    Error() string
}
```

因此兜兜转转又回到了 interface 类型的问题，interface 不是单纯的值，而是**分为类型和值**。

所以传统认知的此 nil 并非彼 nil，**必须得类型和值同时都为 nil 的情况下，interface 的 nil 判断才会为 true**。

在案例一中，结合代码逻辑，更符合场景的是：

```golang
var e *MyErr
e = GetErr()
log.Println(e == nil)
```

输出结果就会是 true。

在案例二中，也是一样的结果，原因也是 interface。不管是 `error` 接口（interface），还是自定义的接口，背后原理一致，自然也就结果一致了。

## 总结

今天这篇文章，相当于是《Go 面试题：Go interface 的一个 “坑” 及原理分析》的变形了，毕竟是生产环境的代码改造而来，更贴合真实的实际场景。

下意识的直觉有时候不是绝对正确的，我们要正确的理解 Go 语言中的那些知识点，才能更好地实现早下班的理想和愿景。



================================================
FILE: content/posts/go/go-golang.md
================================================
---
title: "Go 和 Golang 有什么关系？"
date: 2021-12-31T12:55:12+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

最近天气也冷了，掐指一算是招聘季了，无论是校招、社招、HR、面试官们都蠢蠢欲动。这不，我有一个朋友的 HR 朋友都有起名困难了，一看 Go 语言的工作说明（Job Description），发现各有不同。

如下图：

![来自某招聘网站](https://files.mdnice.com/user/3610/629d4aaa-bb01-4e2b-9a43-d671200da099.png)

仔细一看，有叫 Go 的，也有叫 Golang，还有叫 GO 的。好家伙，Go 语言有这么多个别名，甚至某乎都讨论了起来。到底叫什么是正确的？

为此，今天就由煎鱼带大家理一理，了解这背后的关系。

## Go 官方定义

从网上的资料来看，大家对 Go 的名字还是比较关注的，对于 Go 团队来讲，仿佛经常被问。例如：

- “Go 和 Golang 的关系是什么？”
- “Go、Golang、GO 哪个对？”

甚至在之前探讨 Go2 草案时，也有人开始起 Go2 的名字了，纠结是要叫 “golang2”，还是 “go2lang”：

![](https://files.mdnice.com/user/3610/7608f5a1-9e77-45b2-a552-a7b7c32ad100.png)

其实这是错误的。在 Go FAQ 中有明确的回答这个问题：

![](https://files.mdnice.com/user/3610/bdb43d48-f5c1-41bb-8495-7bbfc2fc60a6.png)

这一门语言称为 “Go”，不叫 “Golang”，也不叫 “GO”。“golang” 只是网站的地址，而不是语言的名称。

同时 “GO” 的语言名称叫法也是错误的，虽然官方上的 Logo 是 “GO”：

![](https://files.mdnice.com/user/3610/67b022a9-49de-4349-861e-77dd25367ac6.png)

但这显然只是设计师层面的美观考量，并不是这一门语言的标准定义。

因此**这一门语言叫做 “Go” 语言**，这是正确的，也得到官方认证的，也不曾改变过。

## 为什么会有 Golang

但可能又有小伙伴疑惑了，那为什么 “Golang” 这个别名，如此之火。到底是为什么？

这里一共有三点原因，分别是：站点地址（Go FAQ 提到）、搜索引擎、社区和论坛、语言重名。

### Go 站点地址

Go 团队所期望的 https://go.org 早就被注册，从网站的底部标识来看，2008 年起建站：

![](https://files.mdnice.com/user/3610/d40e96a2-122c-44fa-8134-2a8b88eb7690.png)

所以 Go 语言只能使用 https://golang.org，你也会 https://pkg.go.dev 和 https://golang.org、https://godoc.org，存在多个域名，并不统一。

因此作为 Go 开发者所常用官方站点，自然而然 golang 这一个语言标识就深深地被记住了，一直沿用至今。

同时域名为 “golang” 关键字，自然会大幅度的影响到 Go 资料搜索引擎的收录，是一个非常重要的因素。

### 搜索引擎

在早年 Go 语言还不知名时，用 go 关键字去搜索资料会非常的困难。这是各大搜索引擎早年的一个槽点（reddit 很多吐槽）。

因为单一的 go 关键字过于广泛了，很多人会直接用 golang 关键字来搜资料，反而会更能看到一些与 Go 真正相关的。

![](https://files.mdnice.com/user/3610/fe21dc19-26d5-4e14-88c5-fa077f149e00.png)

这一点在近年来有明确改善，得益于 Go 语言的崛起，现在也能搜到了。

### 社区和论坛

在社区、论坛等，也有类似的问题。因为占位、重名、认知等原因。像是 segmentfault、twitter 叫 golang。掘金叫 Go，各有不同。

![](https://files.mdnice.com/user/3610/07ee2a59-901f-44ff-bd65-7de95a9878c6.png)

这点难以改善，毕竟各家都是不同企业的。所以难受的点是用户，搜了 Go，可能搜不到，又跑去搜 Golang 才可以。

再看看国外的论坛，在 Google 群组 golang-nuts 和 golang-dev 也有类似偏差。

基本可以明确 **“Golang” 更多会被用在搜索和标签上**，能够保证搜索和标签查询的结果。

### 语言重名 

实际上在 Go 语言出现前，已经存在一门 “Go!” 的编程语言了。有网友表示这也是 Go 官方纠结的一点。

![](https://files.mdnice.com/user/3610/8c2197f0-5376-49c1-845a-b2564606d1a7.png)

不过实际上编程语言重名并不少见，但由于真实性有待考量，建议仅是了解即可。

至少现在已经没有这门语言的命名之争。

## 总结

可以明确，官方诠释的正确名称为 Go。

但由于 go.org 域名的原因，
因此在 Go Programming Language 的通俗称呼下，采取了 golang 来作为 Go 站点、Google 群组的域名/组别等的建立。

Go 资料肯定都集中在官方站点、论坛，自然而然，大家用 “go” 关键字也就很难搜索到了，都得用 “golang” 关键字。

可以明确，**Go 是这一门编程语言的名字，Golang 更多是在搜索和标签上的使用**。

这看上去，是搜索引擎的胜利，你觉得呢？ ：）

================================================
FILE: content/posts/go/go-map-access.md
================================================
---
title: "用 Go map 要注意这个细节，避免依赖他！"
date: 2021-09-12T17:47:29+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。

最近又有同学问我这个日经话题，想转他文章时，结果发现我的公众号竟然没有发过，因此今天我再唠叨两句，好让大家避开这个 “坑”。

有的小伙伴没留意过 Go map 输出、遍历顺序，**以为它是稳定的有序的，会在业务程序中直接依赖这个结果集顺序，结果栽了个大跟头**，吃了线上 BUG。

有的小伙伴知道是无序的，但却不知道为什么,有的却理解错误？

![奇怪的输出结果](http://wx2.sinaimg.cn/large/006fVPCvly1g1s1ah84k8j30k70dvaac.jpg)

今天通过本文，我们将揭开 `for range map` 输出的 “神秘” 面纱，看看它内部实现到底是怎么样的，顺序到底是怎么样？

开始吸鱼之路。

## 前言

例子如下：

```go
func main() {
	m := make(map[int32]string)
	m[0] = "EDDYCJY1"
	m[1] = "EDDYCJY2"
	m[2] = "EDDYCJY3"
	m[3] = "EDDYCJY4"
	m[4] = "EDDYCJY5"

	for k, v := range m {
		log.Printf("k: %v, v: %v", k, v)
	}
}
```

假设运行这段代码，输出的结果是怎么样？是有序，还是无序输出呢？

```
k: 3, v: EDDYCJY4
k: 4, v: EDDYCJY5
k: 0, v: EDDYCJY1
k: 1, v: EDDYCJY2
k: 2, v: EDDYCJY3
```

从输出结果上来讲，是非固定顺序输出的，也就是每次都不一样。但这是为什么呢？

首先**建议你先自己想想原因**。其次我在面试时听过一些说法。有人说因为是哈希的所以就是无（乱）序等等说法。当时我是有点 ？？？

这也是这篇文章出现的原因，希望大家可以一起研讨一下，理清这个问题 ：）

## 看一下汇编

```
    ...
	0x009b 00155 (main.go:11)	LEAQ	type.map[int32]string(SB), AX
	0x00a2 00162 (main.go:11)	PCDATA	$2, $0
	0x00a2 00162 (main.go:11)	MOVQ	AX, (SP)
	0x00a6 00166 (main.go:11)	PCDATA	$2, $2
	0x00a6 00166 (main.go:11)	LEAQ	""..autotmp_3+24(SP), AX
	0x00ab 00171 (main.go:11)	PCDATA	$2, $0
	0x00ab 00171 (main.go:11)	MOVQ	AX, 8(SP)
	0x00b0 00176 (main.go:11)	PCDATA	$2, $2
	0x00b0 00176 (main.go:11)	LEAQ	""..autotmp_2+72(SP), AX
	0x00b5 00181 (main.go:11)	PCDATA	$2, $0
	0x00b5 00181 (main.go:11)	MOVQ	AX, 16(SP)
	0x00ba 00186 (main.go:11)	CALL	runtime.mapiterinit(SB)
	0x00bf 00191 (main.go:11)	JMP	207
	0x00c1 00193 (main.go:11)	PCDATA	$2, $2
	0x00c1 00193 (main.go:11)	LEAQ	""..autotmp_2+72(SP), AX
	0x00c6 00198 (main.go:11)	PCDATA	$2, $0
	0x00c6 00198 (main.go:11)	MOVQ	AX, (SP)
	0x00ca 00202 (main.go:11)	CALL	runtime.mapiternext(SB)
	0x00cf 00207 (main.go:11)	CMPQ	""..autotmp_2+72(SP), $0
	0x00d5 00213 (main.go:11)	JNE	193
	...
```

我们大致看一下整体过程，重点处理 Go map 循环迭代的是两个 runtime 方法，如下：

- runtime.mapiterinit
- runtime.mapiternext

但你可能会想，明明用的是 `for range` 进行循环迭代，怎么出现了这两个函数，怎么回事？

## 看一下转换后

```go
var hiter map_iteration_struct
for mapiterinit(type, range, &hiter); hiter.key != nil; mapiternext(&hiter) {
    index_temp = *hiter.key
    value_temp = *hiter.val
    index = index_temp
    value = value_temp
    original body
}
```

实际上编译器对于 slice 和 map 的循环迭代有不同的实现方式，并不是 `for` 一扔就完事了，还做了一些附加动作进行处理。而上述代码就是 `for range map` 在编译器展开后的伪实现

## 看一下源码

### runtime.mapiterinit

```go
func mapiterinit(t *maptype, h *hmap, it *hiter) {
	...
	it.t = t
	it.h = h
	it.B = h.B
	it.buckets = h.buckets
	if t.bucket.kind&kindNoPointers != 0 {
		h.createOverflow()
		it.overflow = h.extra.overflow
		it.oldoverflow = h.extra.oldoverflow
	}

	r := uintptr(fastrand())
	if h.B > 31-bucketCntBits {
		r += uintptr(fastrand()) << 31
	}
	it.startBucket = r & bucketMask(h.B)
	it.offset = uint8(r >> h.B & (bucketCnt - 1))
	it.bucket = it.startBucket
    ...

	mapiternext(it)
}
```

通过对 `mapiterinit` 方法阅读，可得知其主要用途是在 map 进行遍历迭代时**进行初始化动作**。共有三个形参，用于读取当前哈希表的类型信息、当前哈希表的存储信息和当前遍历迭代的数据

#### 为什么

咱们关注到源码中 `fastrand` 的部分，这个方法名，是不是迷之眼熟。没错，它是一个生成随机数的方法。再看看上下文：

```go
...
// decide where to start
r := uintptr(fastrand())
if h.B > 31-bucketCntBits {
	r += uintptr(fastrand()) << 31
}
it.startBucket = r & bucketMask(h.B)
it.offset = uint8(r >> h.B & (bucketCnt - 1))

// iterator state
it.bucket = it.startBucket
```

在这段代码中，它生成了随机数。用于决定从哪里开始循环迭代。更具体的话就是根据随机数，选择一个桶位置作为起始点进行遍历迭代

因此每次重新 `for range map`，你见到的结果都是不一样的。那是因为它的起始位置根本就不固定！

### runtime.mapiternext

```go
func mapiternext(it *hiter) {
    ...
    for ; i < bucketCnt; i++ {
		...
		k := add(unsafe.Pointer(b), dataOffset+uintptr(offi)*uintptr(t.keysize))
		v := add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+uintptr(offi)*uintptr(t.valuesize))
		...
		if (b.tophash[offi] != evacuatedX && b.tophash[offi] != evacuatedY) ||
			!(t.reflexivekey || alg.equal(k, k)) {
			...
			it.key = k
			it.value = v
		} else {
			rk, rv := mapaccessK(t, h, k)
			if rk == nil {
				continue // key has been deleted
			}
			it.key = rk
			it.value = rv
		}
		it.bucket = bucket
		if it.bptr != b {
			it.bptr = b
		}
		it.i = i + 1
		it.checkBucket = checkBucket
		return
	}
	b = b.overflow(t)
	i = 0
	goto next
}
```

在上小节中，咱们已经选定了起始桶的位置。接下来就是通过 `mapiternext` 进行**具体的循环遍历动作**。该方法主要涉及如下：

- 从已选定的桶中开始进行遍历，寻找桶中的下一个元素进行处理
- 如果桶已经遍历完，则对溢出桶 `overflow buckets` 进行遍历处理

通过对本方法的阅读，可得知其对 buckets 的**遍历规则**以及对于扩容的一些处理（这不是本文重点。因此没有具体展开）

## 总结

在本文开始，咱们先提出核心讨论点：“为什么 Go map 遍历输出是不固定顺序？”。

经过这一番分析，原因也很简单明了。就是 `for range map` 在开始处理循环逻辑的时候，就做了随机播种...

你想问为什么要这么做？

当然是官方有意为之，因为 Go 在早期（1.0）的时候，虽是稳定迭代的，但从结果来讲，其实是无法保证每个 Go 版本迭代遍历规则都是一样的。而这将会导致可移植性问题。

因此，改之。也请不要依赖...

## 参考

- [Go maps in action](https://blog.golang.org/go-maps-in-action)

================================================
FILE: content/posts/go/go-moduels/2019-09-29-goproxy-cn.md
================================================
---

title:      "干货满满的 Go Modules 和 goproxy.cn"
date:       2019-09-29 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - go-modules
---

大家好，我是一只普通的煎鱼，周四晚上很有幸邀请到 goproxy.cn 的作者 @盛傲飞（@aofei） 到 Go 夜读给我们进行第 61 期 《Go Modules、Go Module Proxy 和 goproxy.cn》的技术分享。

本次 @盛傲飞 的夜读分享，是对 Go Modules 的一次很好的解读，比较贴近工程实践，我必然希望把这块的知识更多的分享给大家，因此有了今天本篇文章，同时大家也可以多关注 Go 夜读，每周会通过 zoom 在线直播的方式分享 Go 相关的技术话题，希望对大家有所帮助。

## 前言

Go 1.11 推出的模块（Modules）为 Go 语言开发者打开了一扇新的大门，理想化的依赖管理解决方案使得 Go 语言朝着计算机编程史上的第一个依赖乌托邦（Deptopia）迈进。随着模块一起推出的还有模块代理协议（Module proxy protocol），通过这个协议我们可以实现 Go 模块代理（Go module proxy），也就是依赖镜像。

Go 1.13 的发布为模块带来了大量的改进，所以模块的扶正就是这次 Go 1.13 发布中开发者能直接感觉到的最大变化。而问题在于，Go 1.13 中的 GOPROXY 环境变量拥有了一个在中国大陆无法访问到的默认值 `proxy.golang.org`，经过大家在 golang/go#31755 中激烈的讨论（有些人甚至将话提上升到了“自由世界”的层次），最终 Go 核心团队仍然无法为中国开发者提供一个可在中国大陆访问的官方模块代理。

为了今后中国的 Go 语言开发者能更好地进行开发，七牛云推出了非营利性项目 `goproxy.cn`，其目标是为中国和世界上其他地方的 Gopher 们提供一个免费的、可靠的、持续在线的且经过 CDN 加速的模块代理。可以预见未来是属于模块化的，所以 Go 语言开发者能越早切入模块就能越早进入未来。

如果说 Go 1.11 和 Go 1.12 时由于模块的不完善你不愿意切入，那么 Go 1.13 你则可以大胆地开始放心使用。本次分享将讨论如何使用模块和模块代理，以及在它们的使用中会常遇见的坑，还会讲解如何快速搭建自己的私有模块代理，并简单地介绍一下七牛云推出的 `goproxy.cn` 以及它的出现对于中国 Go 语言开发者来说重要在何处。

## 目录

- Go Modules 简介
- 快速迁移项目至 Go Modules
- 使用 Go Modules 时常遇见的坑
    - 坑 1:判断项目是否启用了 Go Modules
    - 坑 2:管理 Go 的环境变量
    - 坑 3:从 dep、glide 等迁移至 Go Modules
    - 坑 4:拉取私有模块
    - 坑 5:更新现有的模块 
    - 坑 6:主版本号 
- Go Module Proxy 简介
- Goproxy 中国(goproxy.cn)

## Go Modules 简介

![image](https://image.eddycjy.com/765e3c7525bede127297a66e03cf3506.jpg)

Go modules (前身 vgo) 是 Go team (Russ Cox) **强推**的一个**理想化**的**类语言级**依赖管理解决方案，它是和 Go1.11 一同发布的，在 Go1.13 做了大量的优化和调整，目前已经变得比较不错，如果你想用 Go modules，但还停留在 1.11/1.12 版本的话，强烈建议升级。

### 三个关键字

#### 强推
首先这并不是乱说的，因为 Go modules 确实是被强推出来的，如下：
- 之前：大家都知道在 Go modules 之前还有一个叫 dep 的项目，它也是 Go 的一个官方的实验性项目，目的同样也是为了解决 Go 在依赖管理方面的短板。在 Russ Cox 还没有提出 Go modules 的时候，社区里面几乎所有的人都认为 dep 肯定就是未来 Go 官方的依赖管理解决方案了。
- 后来：谁都没想到半路杀出个程咬金，Russ Cox 义无反顾地推出了 Go modules，这瞬间导致一石激起千层浪，让社区炸了锅。大家一致认为 Go team 实在是太霸道、太独裁了，连个招呼都不打一声。我记得当时有很多人在网上跟 Russ Cox 口水战，各种依赖管理解决方案的专家都冒出来发表意见，讨论范围甚至一度超出了 Go 语言的圈子触及到了其他语言的领域。

#### 理想化
从他强制要求使用语义化版本控制这一点来说就很理想化了，如下：
- Go modules 狠到如果你的 Tag 没有遵循语义化版本控制那么它就会忽略你的 Tag，然后根据你的 Commit 时间和哈希值再为你生成一个假定的符合语义化版本控制的版本号。
- Go modules 还默认认为，只要你的主版本号不变，那这个模块版本肯定就不包含 Breaking changes，因为语义化版本控制就是这么规定的啊。是不是很理想化。

#### 类语言级：
这个关键词其实是我自己瞎编的，我只是单纯地个人认为 Go modules 在设计上就像个语言级特性一样，比如如果你的主版本号发生变更，那么你的代码里的 import path 也得跟着变，它认为主版本号不同的两个模块版本是完全不同的两个模块。此外，Go moduels 在设计上跟 go 整个命令都结合得相当紧密，无处不在，所以我才说它是一个有点儿像语言级的特性，虽然不是太严谨。

### 推 Go Modules 的人是谁

那么在上文中提到的 Russ Cox 何许人也呢，很多人应该都知道他，他是 Go 这个项目目前代码提交量最多的人，甚至是第二名的两倍还要多。

Russ Cox 还是 Go 现在的掌舵人（大家应该知道之前 Go 的掌舵人是 Rob Pike，但是听说由于他本人不喜欢特朗普执政所以离开了美国，然后他岁数也挺大的了，所以也正在逐渐交权，不过现在还是在参与 Go 的发展）。

Russ Cox 的个人能力相当强，看问题的角度也很独特，这也就是为什么他刚一提出 Go modules 的概念就能引起那么大范围的响应。虽然是被强推的，但事实也证明当下的 Go modules 表现得确实很优秀，所以这表明一定程度上的 “独裁” 还是可以接受的，至少可以保证一个项目能更加专一地朝着一个方向发展。

总之，无论如何 Go modules 现在都成了 Go 语言的一个密不可分的组件。

### GOPATH

Go modules 出现的目的之一就是为了解决 GOPATH 的问题，也就相当于是抛弃 GOPATH 了。

### Opt-in

Go modules 还处于 Opt-in 阶段，就是你想用就用，不用就不用，不强制你。但是未来很有可能 Go2 就强制使用了。

### "module" != "package"

有一点需要纠正，就是“模块”和“包”，也就是 “module” 和 “package” 这两个术语并不是等价的，是 “集合” 跟 “元素” 的关系，“模块” 包含 “包”，“包” 属于 “模块”，一个 “模块” 是零个、一个或多个 “包” 的集合。

## Go Modules 相关属性

![image](https://image.eddycjy.com/6d9f959fbdf96cc4c8a064b08287e7bc.jpg)

### go.mod

```
module example.com/foobar

go 1.13

require (
    example.com/apple v0.1.2
    example.com/banana v1.2.3
    example.com/banana/v2 v2.3.4
    example.com/pineapple v0.0.0-20190924185754-1b0db40df49a
)

exclude example.com/banana v1.2.4
replace example.com/apple v0.1.2 => example.com/rda v0.1.0 
replace example.com/banana => example.com/hugebanana
```

 go.mod 是启用了 Go moduels 的项目所必须的最重要的文件，它描述了当前项目（也就是当前模块）的元信息，每一行都以一个动词开头，目前有以下 5 个动词:
- module：用于定义当前项目的模块路径。
- go：用于设置预期的 Go 版本。
- require：用于设置一个特定的模块版本。
- exclude：用于从使用中排除一个特定的模块版本。
- replace：用于将一个模块版本替换为另外一个模块版本。

这里的填写格式基本为包引用路径+版本号，另外比较特殊的是 `go $version`，目前从 Go1.13 的代码里来看，还只是个标识作用，暂时未知未来是否有更大的作用。

### go.sum

go.sum 是类似于比如 dep 的 Gopkg.lock 的一类文件，它详细罗列了当前项目直接或间接依赖的所有模块版本，并写明了那些模块版本的 SHA-256 哈希值以备 Go 在今后的操作中保证项目所依赖的那些模块版本不会被篡改。

```
example.com/apple v0.1.2 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ= 
example.com/apple v0.1.2/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU= example.com/banana v1.2.3 h1:qHgHjyoNFV7jgucU8QZUuU4gcdhfs8QW1kw68OD2Lag= 
example.com/banana v1.2.3/go.mod h1:HSdplMjZKSmBqAxg5vPj2TmRDmfkzw+cTzAElWljhcU= example.com/banana/v2 v2.3.4 h1:zl/OfRA6nftbBK9qTohYBJ5xvw6C/oNKizR7cZGl3cI= example.com/banana/v2 v2.3.4/go.mod h1:eZbhyaAYD41SGSSsnmcpxVoRiQ/MPUTjUdIIOT9Um7Q= 
...
```

我们可以看到一个模块路径可能有如下两种：

```
example.com/apple v0.1.2 h1:WXkYYl6Yr3qBf1K79EBnL4mak0OimBfB0XUf9Vl28OQ= 
example.com/apple v0.1.2/go.mod h1:xHWCNGjB5oqiDr8zfno3MHue2Ht5sIBksp03qcyfWMU=
```

前者为 Go modules 打包整个模块包文件 zip 后再进行 hash 值，而后者为针对 go.mod 的 hash 值。他们两者，要不就是同时存在，要不就是只存在 go.mod hash。

那什么情况下会不存在 zip hash 呢，就是当 Go 认为肯定用不到某个模块版本的时候就会省略它的 zip hash，就会出现不存在 zip hash，只存在 go.mod hash 的情况。

### GO111MODULE

这个环境变量主要是 Go modules 的开关，主要有以下参数：

- auto：只在项目包含了 go.mod 文件时启用 Go modules，在 Go 1.13 中仍然是默认值，详见
  ：golang.org/issue/31857。

- on：无脑启用 Go modules，推荐设置，未来版本中的默认值，让 GOPATH 从此成为历史。

- off：禁用 Go modules。

### GOPROXY

这个环境变量主要是用于设置 Go 模块代理，主要如下：

- 它的值是一个以英文逗号 “,” 分割的 Go module proxy 列表（稍后讲解）

  - 作用：用于使 Go 在后续拉取模块版本时能够脱离传统的 VCS 方式从镜像站点快速拉取。它拥有一个默认：`https://proxy.golang.org,direct`，但很可惜 `proxy.golang.org` 在中国无法访问，故而建议使用 `goproxy.cn` 作为替代，可以执行语句：`go env -w GOPROXY=https://goproxy.cn,direct`。

  - 设置为 “off” ：禁止 Go 在后续操作中使用任 何 Go module proxy。

刚刚在上面，我们可以发现值列表中有 “direct” ，它又有什么作用呢。其实值列表中的 “direct” 为特殊指示符，用于指示 Go 回源到模块版本的源地址去抓取(比如 GitHub 等)，当值列表中上一个 Go module proxy 返回 404 或 410 错误时，Go 自动尝试列表中的下一个，遇见 “direct” 时回源，遇见 EOF 时终止并抛出类似 “invalid version: unknown revision...” 的错误。

### GOSUMDB

它的值是一个 Go checksum database，用于使 Go 在拉取模块版本时(无论是从源站拉取还是通过 Go module proxy 拉取)保证拉取到的模块版本数据未经篡改，也可以是“off”即禁止 Go 在后续操作中校验模块版本
- 格式 1：`<SUMDB_NAME>+<PUBLIC_KEY>`。
- 格式 2：`<SUMDB_NAME>+<PUBLIC_KEY> <SUMDB_URL>`。

- 拥有默认值：`sum.golang.org` (之所以没有按照上面的格式是因为 Go 对默认值做了特殊处理)。
- 可被 Go module proxy 代理 (详见：Proxying a Checksum Database)。
- `sum.golang.org` 在中国无法访问，故而更加建议将 GOPROXY 设置为 `goproxy.cn`，因为 `goproxy.cn` 支持代理 `sum.golang.org`。


### Go Checksum Database

Go checksum database 主要用于保护 Go 不会从任何源头拉到被篡改过的非法 Go 模块版本，其作用（左）和工作机制（右）如下图：

![image](https://image.eddycjy.com/8a74a6aa59f5706c5c25836451538a12.jpg)

如果有兴趣的小伙伴可以看看 [Proposal: Secure the Public Go Module Ecosystem](https://go.googlesource.com/proposal/+/master/design/25530-sumdb.md#proxying-a-checksum-database)，有详细介绍其算法机制，如果想简单一点，查看 `go help module-auth` 也是一个不错的选择。


### GONOPROXY/GONOSUMDB/GOPRIVATE

这三个环境变量都是用在当前项目依赖了私有模块，也就是依赖了由 GOPROXY 指定的 Go module proxy 或由 GOSUMDB 指定 Go checksum database 无法访问到的模块时的场景

- 它们三个的值都是一个以英文逗号 “,” 分割的模块路径前缀，匹配规则同 path.Match。
- 其中 GOPRIVATE 较为特殊，它的值将作为 GONOPROXY 和 GONOSUMDB 的默认值，所以建议的最佳姿势是只是用 GOPRIVATE。

在使用上来讲，比如 `GOPRIVATE=*.corp.example.com` 表示所有模块路径以 `corp.example.com` 的下一级域名 (如 `team1.corp.example.com`) 为前缀的模块版本都将不经过 Go module proxy 和 Go checksum database，需要注意的是不包括 `corp.example.com` 本身。

### Global Caching

这个主要是针对 Go modules 的全局缓存数据说明，如下：

- 同一个模块版本的数据只缓存一份，所有其他模块共享使用。
- 目前所有模块版本数据均缓存在 `$GOPATH/pkg/mod`和 ​`$GOPATH/pkg/sum` 下，未来或将移至 `$GOCACHE/mod `和`$GOCACHE/sum` 下( 可能会在当 `$GOPATH` 被淘汰后)。
- 可以使用 `go clean -modcache` 清理所有已缓存的模块版本数据。

另外在 Go1.11 之后 GOCACHE 已经不允许设置为 off 了，我想着这也是为了模块数据缓存移动位置做准备，因此大家应该尽快做好适配。


## 快速迁移项目至 Go Modules

- 第一步: 升级到 Go 1.13。
- 第二步: 让 GOPATH 从你的脑海中完全消失，早一步踏入未来。
    - 修改 GOBIN 路径（可选）：`go env -w GOBIN=$HOME/bin`。
    - 打开 Go modules：`go env -w GO111MODULE=on`。
    - 设置 GOPROXY：`go env -w GOPROXY=https://goproxy.cn,direct` # 在中国是必须的，因为它的默认值被墙了。
- 第三步(可选): 按照你喜欢的目录结构重新组织你的所有项目。
- 第四步: 在你项目的根目录下执行 `go mod init <OPTIONAL_MODULE_PATH>` 以生成 go.mod 文件。
- 第五步: 想办法说服你身边所有的人都去走一下前四步。


## 迁移后 go get 行为的改变

- 用 `go help module-get` 和 `go help gopath-get`分别去了解 Go modules 启用和未启用两种状态下的 go get 的行为
- 用 `go get` 拉取新的依赖
   - 拉取最新的版本(优先择取 tag)：`go get golang.org/x/text@latest`
   - 拉取 `master` 分支的最新 commit：`go get golang.org/x/text@master`
   - 拉取 tag 为 v0.3.2 的 commit：`go get golang.org/x/text@v0.3.2`
   - 拉取 hash 为 342b231 的 commit，最终会被转换为 v0.3.2：`go get golang.org/x/text@342b2e`
   - 用 `go get -u` 更新现有的依赖
   - 用 `go mod download` 下载 go.mod 文件中指明的所有依赖
   - 用 `go mod tidy` 整理现有的依赖
   - 用 `go mod graph` 查看现有的依赖结构
   - 用 `go mod init` 生成 go.mod 文件 (Go 1.13 中唯一一个可以生成 go.mod 文件的子命令)
- 用 `go mod edit` 编辑 go.mod 文件
- 用 `go mod vendor` 导出现有的所有依赖 (事实上 Go modules 正在淡化 Vendor 的概念)
- 用 `go mod verify` 校验一个模块是否被篡改过

这里我们注意到有两点比较特别，分别是：

- 第一点：为什么 “拉取 hash 为 342b231 的 commit，最终会被转换为 v0.3.2” 呢。这是因为虽然我们设置了拉取 @342b2e commit，但是因为 Go modules 会与 tag 进行对比，若发现对应的 commit 与 tag 有关联，则进行转换。
- 第二点：为什么不建议使用 `go mod vendor`，因为 Go modules 正在淡化 Vendor 的概念，很有可能 Go2 就去掉了。

## 使用 Go Modules 时常遇见的坑

### 坑 1: 判断项目是否启用了 Go Modules

![image](https://image.eddycjy.com/0dda1c26b7aa3f9e8655c8e366f49116.jpg)



### 坑 2: 管理 Go 的环境变量

![image](https://image.eddycjy.com/78a93176b5e24dfde88327aebe63fe9c.jpg)

这里主要是提到 Go1.13 新增了 `go env -w` 用于写入环境变量，而写入的地方是 `os.UserConfigDir` 所返回的路径，需要注意的是 `go env -w` 不会覆写。

### 坑 3: 从 dep、glide 等迁移至 Go Modules

![image](https://image.eddycjy.com/67c83f5d4a3d936449a705921fcfe492.jpg)

这里主要是指从旧有的依赖包管理工具（dep/glide 等）进行迁移时，因为 BUG 的原因会导致不经过 GOPROXY 的代理，解决方法有如下两个：

- 手动创建一个 go.mod 文件，再执行 go mod tidy 进行补充。
- 上代理，相当于不使用 GOPROXY 了。

### 坑 4:拉取私有模块

![image](https://image.eddycjy.com/075bdc3d3552c000981c9d4fdd8d0f3f.jpg)

这里主要想涉及两块知识点，如下：

- GOPROXY 是无权访问到任何人的私有模块的，所以你放心，安全性没问题。
- GOPROXY 除了设置模块代理的地址以外，还需要增加 “direct” 特殊标识才可以成功拉取私有库。

### 坑 5:更新现有的模块

![image](https://image.eddycjy.com/d35e9f465d82a14c53fcca3ff5ebc557.jpg)

### 坑 6:主版本号 

![image](https://image.eddycjy.com/75778deb206803598e48693f6fea60b8.jpg)



## Go Module Proxy 简介

![image](https://image.eddycjy.com/20cb4e449ab50de36a880e3b22e1e8d8.jpg)

在这里再次强调了 Go Module Proxy 的作用（图左），以及其对应的协议交互流程（图右），有兴趣的小伙伴可以认真看一下。

## Goproxy 中国(goproxy.cn)

在这块主要介绍了  Goproxy 的实践操作以及 goproxy.cn 的一些 Q&A 和 近况，如下：

### Q&A

**Q：如果中国 Go 语言社区没有咱们自己家的 Go Module Proxy 会怎么样？**

**A：**在 Go 1.13 中 GOPROXY 和 GOSUMDB 这两个环境变量都有了在中国无法 访问的默认值，尽管我在 golang.org/issue/31755 里努力尝 试过，但最终仍然无法为咱们中国的 Go 语言开发者谋得一个完美的解决方案。所以从今以后咱 们中国的所有 Go 语言开发者，只要是 使用了 Go modules 的，那么都必须先修改 GOPROXY 和 GOSUMDB 才能正常使用 Go 做开发，否则可能连一个最简单的程序都跑不起 来(只要它有依 赖第三方模 块)。



**Q： 我创建 Goproxy 中国(goproxy.cn)的主要原因？**

**A：**其实更早的时候，也就是今年年初我也曾 试图在 golang.org/issue/31020 中请求 Go team 能想办法避免那时的 GOPROXY 即将拥有的默认值可以在中国正常访问，但 Go team 似乎也无能为力，为此我才坚定了创建 goproxy.cn 的信念。既然别人没法儿帮忙，那咱们就 得自己动手，不为别的，就为了让大家以后能够更愉快地使用 Go 语言配合 Go modules 做开发。

最初我先是和七牛云的 许叔(七牛云的 创始人兼 CEO 许式伟)提出了我打算 创建 goproxy.cn 的想法，本是抱着 试试看的目的，但没想 到 许叔几乎是没有超过一分钟的考虑便认可了我的想法并表示愿意一起推 动。那一阵子刚好赶上我在写毕业论文，所以项目开发完后就 一直没和七牛云做交接，一直跑在我的个人服 务器上。直到有一次 goproxy.cn 被攻击了，一下午的功夫 烧了我一百多美元，然后我才 意识到这种项目真不能个人来做。个人来做不靠 谱，万一依赖这个项目的人多了，项目再出什么事儿，那就会给大家􏰁成不必要的损 失。所以我赶紧和七牛云做了交接，把 goproxy.cn 完全交给了七牛云，甚至连域名都过户了去。



### 近况

![image](https://image.eddycjy.com/7bf56751651d56edb989f7cfd64c0006.png)

- Goproxy 中国 (goproxy.cn) 是目前中国最可靠的 Go module proxy (真不是在自卖自夸)。
- 为中国 Go 语言开发者量身打􏰁，支持代理 GOSUMDB 的默认值，经过全球 CDN 加速，高可用，可 应用进公司复杂的开发环境中，亦可用作上游代理。
- 由中国倍受信赖的云服务提供商七牛云无偿提供基础设施支持的开源的非营利性项目。
- 目标是为中国乃至全世界的 Go 语言开发者提供一个免 费的、可靠的、持 续在线的且经过 CDN 加􏰀的 Go module proxy。
- 域名已由七牛云进行了备案 (沪ICP备11037377号-56)。

### 情况

![image](https://image.eddycjy.com/aa517d9e93aff49762de76f601702eb1.jpg)

此处呈现的是存储大小，主要是针对模块包代码，而一般来讲代码并不会有多大，0-10MB，10-50MB 占最大头，也是能够理解，但是大于 100MB 的模块包代码就比较夸张了。

![image](https://image.eddycjy.com/94bbc93b83f87b43b254f5f15ff995e7.jpg)

此时主要是展示了一下近期 goproxy.cn 的网络数据情况，我相信未来是会越来越高的，值得期待。



## Q&A


**Q：如何解决 Go 1.13 在从 GitLab 拉取模块版本时遇到的，Go 错误地按照非期望值的路径寻找目标模块版本结果致使最终目标模块拉取失败的问题？**

**A：**GitLab 中配合 goget 而设置的 `<meta>` 存在些许问题，导致 Go 1.13 错误地识别了模块的具体路径，这是个 Bug，据说在 GitLab 的新版本中已经被修复了，详细内容可以看 https://github.com/golang/go/issues/34094 这个 Issue。然后目前的解决办法的话除了升级 GitLab 的版本外，还可以参考 https://github.com/developer-learning/night-reading-go/issues/468#issuecomment-535850154 这条回复。

**Q：使用 Go modules 时可以同时依赖同一个模块的不同的两个或者多个小版本（修订版本号不同）吗？**

**A：**不可以的，Go modules 只可以同时依赖一个模块的不同的两个或者多个大版本（主版本号不同）。比如可以同时依赖 example.com/foobar@v1.2.3 和 example.com/foobar/v2@v2.3.4，因为他们的模块路径（module path）不同，Go modules 规定主版本号不是 v0 或者 v1 时，那么主版本号必须显式地出现在模块路径的尾部。但是，同时依赖两个或者多个小版本是不支持的。比如如果模块 A 同时直接依赖了模块 B 和模块 C，且模块 A 直接依赖的是模块 C 的 v1.0.0 版本，然后模块 B 直接依赖的是模块 C 的 v1.0.1 版本，那么最终 Go modules 会为模块 A 选用模块 C 的 v1.0.1 版本而不是模块 A 的 go.mod 文件中指明的 v1.0.0 版本。

这是因为 Go modules 认为只要主版本号不变，那么剩下的都可以直接升级采用最新的。但是如果采用了最新的结果导致项目 Break 掉了，那么 Go modules 就会 Fallback 到上一个老的版本，比如在前面的例子中就会 Fallback 到 v1.0.0 版本。

**Q：在 go.sum 文件中的一个模块版本的 Hash 校验数据什么情况下会成对出现，什么情况下只会存在一行？**

**A：**通常情况下，在 go.sum 文件中的一个模块版本的 Hash 校验数据会有两行，前一行是该模块的 ZIP 文件的 Hash 校验数据，后一行是该模块的 go.mod 文件的 Hash 校验数据。但是也有些情况下只会出现一行该模块的 go.mod 文件的 Hash 校验数据，而不包含该模块的 ZIP 文件本身的 Hash 校验数据，这个情况发生在 Go modules 判定为你当前这个项目完全用不到该模块，根本也不会下载该模块的 ZIP 文件，所以就没必要对其作出 Hash 校验保证，只需要对该模块的 go.mod 文件作出 Hash 校验保证即可，因为 go.mod 文件是用得着的，在深入挖取项目依赖的时候要用。

**Q：能不能更详细地讲解一下 go.mod 文件中的 replace 动词的行为以及用法？**

**A：**这个 replace 动词的作用是把一个“模块版本”替换为另外一个“模块版本”，这是“模块版本”和“模块版本（module path）”之间的替换，“=>”标识符前面的内容是待替换的“模块版本”的“模块路径”，后面的内容是要替换的目标“模块版本”的所在地，即路径，这个路径可以是一个本地磁盘的相对路径，也可以是一个本地磁盘的绝对路径，还可以是一个网络路径，但是这个目标路径并不会在今后你的项目代码中作为你“导入路径（import path）”出现，代码里的“导入路径”还是得以你替换成的这个目标“模块版本”的“模块路径”作为前缀。

另外需要注意，Go modules 是不支持在 “导入路径” 里写相对路径的。举个例子，如果项目 A 依赖了模块 B，比如模块 B 的“模块路径”是 example.com/b，然后它在的磁盘路径是 ~/b，在项目 A 里的 go.mod 文件中你有一行 replace example.com/b=>~/b，然后在项目 A 里的代码中的“导入路基”就是 import"example.com/b"，而不是 import"~/b"，剩下的工作是 Go modules 帮你自动完成了的。

然后就是我在分享中也提到了， exclude 和 replace 这两个动词只作用于当前主模块，也就是当前项目，它所依赖的那些其他模块版本中如果出现了你待替换的那个模块版本的话，Go modules 还是会为你依赖的那个模块版本去拉取你的这个待替换的模块版本。

举个例子，比如项目 A 直接依赖了模块 B 和模块 C，然后模块 B 也直接依赖了模块 C，那么你在项目 A 中的 go.mod 文件里的 replace c=>~/some/path/c 是只会影响项目 A 里写的代码中，而模块 B 所用到的还是你 replace 之前的那个 c，并不是你替换成的 ~/some/path/c 这个。


## 总结

在 Go1.13 发布后，接触 Go modules 和 Go module proxy 的人越来越多，经常在各种群看到各种小伙伴在咨询，包括我自己也贡献了好几枚 “坑”，因此我觉得傲飞的这一次 《Go Modules、Go Module Proxy 和 goproxy.cn》的技术分享，非常的有实践意义。如果后续大家还有什么建议或问题，欢迎随时来讨论。

最后，感谢 goproxy.cn 背后的人们（@七牛云 和 @盛傲飞）对中国 Go 语言社区的无私贡献和奉献。


## 进一步阅读

- [night-reading-go/issues/468](https://github.com/developer-learning/night-reading-go/issues/468)
- [B站：【Go 夜读】第 61 期 Go Modules、Go Module Proxy 和 goproxy.cn](https://www.bilibili.com/video/av69111199?from=search&seid=14251207475086319821)
- [youtube：【Go 夜读】第 61 期 Go Modules、Go Module Proxy 和 goproxy.cn](https://www.youtube.com/watch?v=H3LVVwZ9zNY)




================================================
FILE: content/posts/go/go-moduels/2020-02-28-go-modules.md
================================================
---
title:      "Go Modules 终极入门"
date:       2020-02-28 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - go-modules
---

Go modules 是 Go 语言中正式官宣的项目依赖解决方案，Go modules（前身为vgo）于 Go1.11 正式发布，在 Go1.14 已经准备好，并且可以用在生产上（ready for production）了，Go官方也鼓励所有用户从其他依赖项管理工具迁移到 Go modules。

而 Go1.14，在近期也终于正式发布，Go 官方亲自 “喊” 你来用：

![image](https://image.eddycjy.com/243fb2cca64972b2f36827f59b26d840.jpeg)


因此在今天这篇文章中，我将给大家带来 Go modules 的 “终极入门”，欢迎大家一起共同探讨。

Go modules 是 Go 语言中正式官宣的项目依赖管理工具，Go modules（前身为vgo）于 Go1.11 正式发布，在 Go1.14 已经准备好，并且可以用在生产上（ready for production）了，鼓励所有用户从其他依赖项管理工具迁移到 Go modules。

## 什么是Go Modules

Go modules 是 Go 语言的依赖解决方案，发布于 Go1.11，成长于 Go1.12，丰富于 Go1.13，正式于 Go1.14 推荐在生产上使用。

Go moudles 目前集成在 Go 的工具链中，只要安装了 Go，自然而然也就可以使用 Go moudles 了，而 Go modules 的出现也解决了在 Go1.11 前的几个常见争议问题：

1. Go 语言长久以来的依赖管理问题。
2. “淘汰”现有的 GOPATH 的使用模式。
3. 统一社区中的其它的依赖管理工具（提供迁移功能）。

## GOPATH的那些点点滴滴

我们有提到 Go modules 的解决的问题之一就是“淘汰”掉 GOPATH，但是 GOPATH 又是什么呢，为什么在 Go1.11 前就使用 GOPATH，而 Go1.11 后就开始逐步建议使用 Go modules，不再推荐 GOPATH 的模式了呢？

### GOPATH是什么

我们先看看第一个问题，GOPATH 是什么，我们可以输入如下命令查看：

```
$ go env
GOPATH="/Users/eddycjy/go"
...
```

我们输入`go env`命令行后可以查看到 GOPATH 变量的结果，我们进入到该目录下进行查看，如下：

```
go
├── bin
├── pkg
└── src
    ├── github.com
    ├── golang.org
    ├── google.golang.org
    ├── gopkg.in
    ....
```

GOPATH目录下一共包含了三个子目录，分别是：

- bin：存储所编译生成的二进制文件。
- pkg：存储预编译的目标文件，以加快程序的后续编译速度。
- src：存储所有`.go`文件或源代码。在编写 Go 应用程序，程序包和库时，一般会以`$GOPATH/src/github.com/foo/bar`的路径进行存放。

因此在使用 GOPATH 模式下，我们需要将应用代码存放在固定的`$GOPATH/src`目录下，并且如果执行`go get`来拉取外部依赖会自动下载并安装到`$GOPATH`目录下。

### 为什么弃用GOPATH模式

在 GOPATH 的 `$GOPATH/src` 下进行 `.go` 文件或源代码的存储，我们可以称其为 GOPATH 的模式，这个模式，看起来好像没有什么问题，那么为什么我们要弃用呢，参见如下原因：

- GOPATH 模式下没有版本控制的概念，具有致命的缺陷，至少会造成以下问题：
  - 在执行`go get`的时候，你无法传达任何的版本信息的期望，也就是说你也无法知道自己当前更新的是哪一个版本，也无法通过指定来拉取自己所期望的具体版本。
  - 在运行Go应用程序的时候，你无法保证其它人与你所期望依赖的第三方库是相同的版本，也就是说在项目依赖库的管理上，你无法保证所有人的依赖版本都一致。
  - 你没办法处理 v1、v2、v3 等等不同版本的引用问题，因为 GOPATH 模式下的导入路径都是一样的，都是`github.com/foo/bar`。
- Go 语言官方从 Go1.11 起开始推进 Go modules（前身vgo），Go1.13 起不再推荐使用 GOPATH 的使用模式，Go modules 也渐趋稳定，因此新项目也没有必要继续使用GOPATH模式。

### 在GOPATH模式下的产物

Go1 在 2012 年 03 月 28 日发布，而 Go1.11 是在 2018 年 08 月 25 日才正式发布（数据来源：Github Tag），在这个空档的时间内，并没有 Go modules 这一个东西，最早期可能还好说，因为刚发布，用的人不多，所以没有明显暴露，但是后期 Go 语言使用的人越来越多了，那怎么办？

这时候社区中逐渐的涌现出了大量的依赖解决方案，百花齐放，让人难以挑选，其中包括我们所熟知的 vendor 目录的模式，以及曾经一度被认为是“官宣”的 dep 的这类依赖管理工具。

但为什么 dep 没有正在成为官宣呢，其实是因为随着 Russ Cox 与 Go 团队中的其他成员不断深入地讨论，发现dep 的一些细节似乎越来越不适合 Go，因此官方采取了另起 proposal 的方式来推进，其方案的结果一开始先是释出 vgo（Go modules的前身，知道即可，不需要深入了解），最终演变为我们现在所见到的 Go modules，也在 Go1.11 正式进入了 Go 的工具链。

因此与其说是 “在GOPATH模式下的产物”，不如说是历史为当前提供了重要的教训，因此出现了 Go modules。

## Go Modules基本使用

在初步了解了 Go modules 的前世今生后，我们正式进入到 Go modules 的使用，首先我们将从头开始创建一个 Go modules 的项目（原则上所创建的目录应该不要放在 GOPATH 之中）。

### 所提供的命令

在 Go modules 中，我们能够使用如下命令进行操作：

| 命令            | 作用                             |
| --------------- | -------------------------------- |
| go mod init     | 生成 go.mod 文件                 |
| go mod download | 下载 go.mod 文件中指明的所有依赖 |
| go mod tidy     | 整理现有的依赖                   |
| go mod graph    | 查看现有的依赖结构               |
| go mod edit     | 编辑 go.mod 文件                 |
| go mod vendor   | 导出项目所有的依赖到vendor目录   |
| go mod verify   | 校验一个模块是否被篡改过         |
| go mod why      | 查看为什么需要依赖某模块         |

### 所提供的环境变量

在 Go modules 中有如下常用环境变量，我们可以通过 `go env` 命令来进行查看，如下：

```
$ go env
GO111MODULE="auto"
GOPROXY="https://proxy.golang.org,direct"
GONOPROXY=""
GOSUMDB="sum.golang.org"
GONOSUMDB=""
GOPRIVATE=""
...
```

#### GO111MODULE

Go语言提供了 GO111MODULE 这个环境变量来作为 Go modules 的开关，其允许设置以下参数：

- auto：只要项目包含了 go.mod 文件的话启用 Go modules，目前在 Go1.11 至 Go1.14 中仍然是默认值。
- on：启用 Go modules，推荐设置，将会是未来版本中的默认值。
- off：禁用 Go modules，不推荐设置。

##### GO111MODULE的小历史

你可能会留意到 GO111MODULE 这个名字比较“奇特”，实际上在 Go 语言中经常会有这类阶段性的变量， GO111MODULE 这个命名代表着Go语言在 1.11 版本添加的，针对 Module 的变量。

像是在 Go1.5 版本的时候，也发布了一个系统环境变量 GO15VENDOREXPERIMENT，作用是用于开启 vendor 目录的支持，当时其默认值也不是开启，仅仅作为 experimental。其随后在 Go1.6 版本时也将默认值改为了开启，并且最后作为了official，GO15VENDOREXPERIMENT 系统变量就退出了历史舞台。

而未来 GO111MODULE 这一个系统环境变量也会面临这个问题，也会先调整为默认值为 on（曾经在Go1.13想想改为 on，并且已经合并了 PR，但最后因为种种原因改回了 auto），然后再把 GO111MODULE 的支持给去掉，我们猜测应该会在 Go2 将 GO111MODULE 给去掉，因为如果直接去掉 GO111MODULE 的支持，会存在兼容性问题。

#### GOPROXY

这个环境变量主要是用于设置 Go 模块代理（Go module proxy），其作用是用于使 Go 在后续拉取模块版本时能够脱离传统的 VCS 方式，直接通过镜像站点来快速拉取。

GOPROXY 的默认值是：`https://proxy.golang.org,direct`，这有一个很严重的问题，就是 `proxy.golang.org` 在国内是无法访问的，因此这会直接卡住你的第一步，所以你必须在开启 Go modules 的时，同时设置国内的 Go 模块代理，执行如下命令：

```
$ go env -w GOPROXY=https://goproxy.cn,direct
```

GOPROXY的值是一个以英文逗号 “,” 分割的 Go 模块代理列表，允许设置多个模块代理，假设你不想使用，也可以将其设置为 “off” ，这将会禁止 Go 在后续操作中使用任何 Go 模块代理。

##### direct是什么

而在刚刚设置的值中，我们可以发现值列表中有 “direct” 标识，它又有什么作用呢？

实际上 “direct” 是一个特殊指示符，用于指示 Go 回源到模块版本的源地址去抓取（比如 GitHub 等），场景如下：当值列表中上一个 Go 模块代理返回 404 或 410 错误时，Go 自动尝试列表中的下一个，遇见 “direct” 时回源，也就是回到源地址去抓取，而遇见 EOF 时终止并抛出类似 “invalid version: unknown revision...” 的错误。

#### GOSUMDB

它的值是一个 Go checksum database，用于在拉取模块版本时（无论是从源站拉取还是通过 Go module proxy 拉取）保证拉取到的模块版本数据未经过篡改，若发现不一致，也就是可能存在篡改，将会立即中止。

GOSUMDB的默认值为：`sum.golang.org`，在国内也是无法访问的，但是 GOSUMDB 可以被 Go 模块代理所代理（详见：Proxying a Checksum Database）。

因此我们可以通过设置 GOPROXY 来解决，而先前我们所设置的模块代理 `goproxy.cn` 就能支持代理 `sum.golang.org`，所以这一个问题在设置 GOPROXY 后，你可以不需要过度关心。

另外若对 GOSUMDB 的值有自定义需求，其支持如下格式：

- 格式 1：`<SUMDB_NAME>+<PUBLIC_KEY>`。
- 格式 2：`<SUMDB_NAME>+<PUBLIC_KEY> <SUMDB_URL>`。

也可以将其设置为“off”，也就是禁止 Go 在后续操作中校验模块版本。

#### GONOPROXY/GONOSUMDB/GOPRIVATE

这三个环境变量都是用在当前项目依赖了私有模块，例如像是你公司的私有 git 仓库，又或是 github 中的私有库，都是属于私有模块，都是要进行设置的，否则会拉取失败。

更细致来讲，就是依赖了由 GOPROXY 指定的 Go 模块代理或由 GOSUMDB 指定 Go checksum database 都无法访问到的模块时的场景。

而一般建议直接设置 GOPRIVATE，它的值将作为 GONOPROXY 和 GONOSUMDB 的默认值，所以建议的最佳姿势是直接使用 GOPRIVATE。

并且它们的值都是一个以英文逗号 “,” 分割的模块路径前缀，也就是可以设置多个，例如：

```
$ go env -w GOPRIVATE="git.example.com,github.com/eddycjy/mquote"
```

设置后，前缀为 git.xxx.com 和 github.com/eddycjy/mquote 的模块都会被认为是私有模块。

如果不想每次都重新设置，我们也可以利用通配符，例如：

```
$ go env -w GOPRIVATE="*.example.com"
```

这样子设置的话，所有模块路径为 example.com 的子域名（例如：git.example.com）都将不经过 Go module proxy 和 Go checksum database，需要注意的是不包括 example.com 本身。

### 开启Go Modules

目前Go modules并不是默认开启，因此Go语言提供了GO111MODULE这个环境变量来作为Go modules的开关，其允许设置以下参数：

- auto：只要项目包含了go.mod文件的话启用 Go modules，目前在Go1.11至Go1.14中仍然是默认值。
- on：启用 Go modules，推荐设置，将会是未来版本中的默认值。
- off：禁用 Go modules，不推荐设置。

如果你不确定你当前的值是什么，可以执行`go env`命令，查看结果：

```
$ go env
GO111MODULE="off"
...
```

如果需要对GO111MODULE的值进行变更，推荐通过`go env`命令进行设置：

```
 $ go env -w GO111MODULE=on
```

但是需要注意的是如果对应的系统环境变量有值了（进行过设置），会出现如下警告信息：`warning: go env -w GO111MODULE=... does not override conflicting OS environment variable`。

又或是可以通过直接设置系统环境变量（写入对应的.bash_profile文件亦可）来实现这个目的：

```
$ export GO111MODULE=on
```

### 初始化项目

在完成 Go modules 的开启后，我们需要创建一个示例项目来进行演示，执行如下命令：

```
$ mkdir -p $HOME/eddycjy/module-repo 
$ cd $HOME/eddycjy/module-repo
```

然后进行Go modules的初始化，如下：

```
$ go mod init github.com/eddycjy/module-repo
go: creating new go.mod: module github.com/eddycjy/module-repo
```

在执行 `go mod init` 命令时，我们指定了模块导入路径为 `github.com/eddycjy/module-repo`。接下来我们在该项目根目录下创建 main.go 文件，如下：

```
package main

import (
    "fmt"
    "github.com/eddycjy/mquote"
)

func main() {
	fmt.Println(mquote.GetHello())
}
```

然后在项目根目录执行 `go get github.com/eddycjy/mquote` 命令，如下：

```
$ go get github.com/eddycjy/mquote 
go: finding github.com/eddycjy/mquote latest
go: downloading github.com/eddycjy/mquote v0.0.0-20200220041913-e066a990ce6f
go: extracting github.com/eddycjy/mquote v0.0.0-20200220041913-e066a990ce6f
```

### 查看go.mod 文件

在初始化项目时，会生成一个 go.mod 文件，是启用了 Go modules 项目所必须的最重要的标识，同时也是GO111MODULE 值为 auto 时的识别标识，它描述了当前项目（也就是当前模块）的元信息，每一行都以一个动词开头。

在我们刚刚进行了初始化和简单拉取后，我们再次查看go.mod文件，基本内容如下：

```
module github.com/eddycjy/module-repo

go 1.13

require (
	github.com/eddycjy/mquote v0.0.0-20200220041913-e066a990ce6f
)
```

为了更进一步的讲解，我们模拟引用如下：

```
module github.com/eddycjy/module-repo

go 1.13

require (
    example.com/apple v0.1.2
    example.com/banana v1.2.3
    example.com/banana/v2 v2.3.4
    example.com/pear // indirect
    example.com/strawberry // incompatible
)

exclude example.com/banana v1.2.4
replace example.com/apple v0.1.2 => example.com/fried v0.1.0 
replace example.com/banana => example.com/fish
```

- module：用于定义当前项目的模块路径。
- go：用于标识当前模块的 Go 语言版本，值为初始化模块时的版本，目前来看还只是个标识作用。
- require：用于设置一个特定的模块版本。
- exclude：用于从使用中排除一个特定的模块版本。
- replace：用于将一个模块版本替换为另外一个模块版本。

另外你会发现 `example.com/pear` 的后面会有一个 indirect 标识，indirect 标识表示该模块为间接依赖，也就是在当前应用程序中的 import 语句中，并没有发现这个模块的明确引用，有可能是你先手动 `go get` 拉取下来的，也有可能是你所依赖的模块所依赖的，情况有好几种。

### 查看go.sum文件

在第一次拉取模块依赖后，会发现多出了一个 go.sum 文件，其详细罗列了当前项目直接或间接依赖的所有模块版本，并写明了那些模块版本的 SHA-256 哈希值以备 Go 在今后的操作中保证项目所依赖的那些模块版本不会被篡改。

```
github.com/eddycjy/mquote v0.0.1 h1:4QHXKo7J8a6J/k8UA6CiHhswJQs0sm2foAQQUq8GFHM=
github.com/eddycjy/mquote v0.0.1/go.mod h1:ZtlkDs7Mriynl7wsDQ4cU23okEtVYqHwl7F1eDh4qPg=
github.com/eddycjy/mquote/module/tour v0.0.1 h1:cc+pgV0LnR8Fhou0zNHughT7IbSnLvfUZ+X3fvshrv8=
github.com/eddycjy/mquote/module/tour v0.0.1/go.mod h1:8uL1FOiQJZ4/1hzqQ5mv4Sm7nJcwYu41F3nZmkiWx5I=
...
```

我们可以看到一个模块路径可能有如下两种：

```
github.com/eddycjy/mquote v0.0.1 h1:4QHXKo7J8a6J/k8UA6CiHhswJQs0sm2foAQQUq8GFHM=
github.com/eddycjy/mquote v0.0.1/go.mod h1:ZtlkDs7Mriynl7wsDQ4cU23okEtVYqHwl7F1eDh4qPg=
```

h1 hash 是 Go modules 将目标模块版本的 zip 文件开包后，针对所有包内文件依次进行 hash，然后再把它们的 hash 结果按照固定格式和算法组成总的 hash 值。

而 h1 hash 和 go.mod hash 两者，要不就是同时存在，要不就是只存在 go.mod hash。那什么情况下会不存在 h1 hash 呢，就是当 Go 认为肯定用不到某个模块版本的时候就会省略它的 h1 hash，就会出现不存在 h1 hash，只存在 go.mod hash 的情况。

### 查看全局缓存

我们刚刚成功的将 `github.com/eddycjy/mquote` 模块拉取了下来，其拉取的结果缓存在  `$GOPATH/pkg/mod`和 `$GOPATH/pkg/sumdb` 目录下，而在`mod`目录下会以 `github.com/foo/bar` 的格式进行存放，如下：

```
mod
├── cache
├── github.com
├── golang.org
├── google.golang.org
├── gopkg.in
...
```

需要注意的是同一个模块版本的数据只缓存一份，所有其它模块共享使用。如果你希望清理所有已缓存的模块版本数据，可以执行 `go clean -modcache` 命令。

## Go Modules下的go get行为

在拉取项目依赖时，你会发现拉取的过程总共分为了三大步，分别是 finding（发现）、downloading（下载）以及 extracting（提取）， 并且在拉取信息上一共分为了三段内容：

![image](https://image.eddycjy.com/a78b16231e7c0164e0acccb7abdd01be.jpg)

需要注意的是，所拉取版本的 commit 时间是以UTC时区为准，而并非本地时区，同时我们会发现我们 `go get` 命令所拉取到的版本是 v0.0.0，这是因为我们是直接执行 `go get -u` 获取的，并没有指定任何的版本信息，由 Go modules 自行按照内部规则进行选择。

### go get的拉取行为

刚刚我们用 `go get` 命令拉取了新的依赖，那么 `go get` 又提供了哪些功能呢，常用的拉取命令如下：

| 命令               | 作用                                                         |
| ------------------ | ------------------------------------------------------------ |
| go get             | 拉取依赖，会进行指定性拉取（更新），并不会更新所依赖的其它模块。 |
| go get -u          | 更新现有的依赖，会强制更新它所依赖的其它全部模块，不包括自身。 |
| go get -u -t ./... | 更新所有直接依赖和间接依赖的模块版本，包括单元测试中用到的。 |

那么我想选择具体版本应当如何执行呢，如下：

| 命令                            | 作用                                                    |
| ------------------------------- | ------------------------------------------------------- |
| go get golang.org/x/text@latest | 拉取最新的版本，若存在tag，则优先使用。                 |
| go get golang.org/x/text@master | 拉取 master 分支的最新 commit。                         |
| go get golang.org/x/text@v0.3.2 | 拉取 tag 为 v0.3.2 的 commit。                          |
| go get golang.org/x/text@342b2e | 拉取 hash 为 342b231 的 commit，最终会被转换为 v0.3.2。 |

### go get的版本选择

我们回顾一下我们拉取的 `go get github.com/eddycjy/mquote`，其结果是 `v0.0.0-20200220041913-e066a990ce6f`，对照着上面所提到的 `go get` 行为来看，你可能还会有一些疑惑，那就是在 `go get` 没有指定任何版本的情况下，它的版本选择规则是怎么样的，也就是为什么 `go get` 拉取的是 `v0.0.0`，它什么时候会拉取正常带版本号的 tags 呢。实际上这需要区分两种情况，如下：

1. 所拉取的模块有发布 tags：
   - 如果只有单个模块，那么就取主版本号最大的那个tag。
   - 如果有多个模块，则推算相应的模块路径，取主版本号最大的那个tag（子模块的tag的模块路径会有前缀要求）
2. 所拉取的模块没有发布过 tags：
   - 默认取主分支最新一次 commit 的 commithash。

#### 没有发布过 tags

那么为什么会拉取的是 `v0.0.0` 呢，是因为 `github.com/eddycjy/mquote` 没有发布任何的tag，如下：

![image](https://image.eddycjy.com/25989c9757d0dfba50789a1bb327edab.jpg)

因此它默认取的是主分支最新一次 commit 的 commit 时间和 commithash，也就是 `20200220041913-e066a990ce6f`，属于第二种情况。

#### 有发布 tags

在项目有发布 tags 的情况下，还存在着多种模式，也就是只有单个模块和多个模块，我们统一以多个模块来进行展示，因为多个模块的情况下就已经包含了单个模块的使用了，如下图：

![image](https://image.eddycjy.com/5e9cd4d15161f478e797c800e29cf2fd.jpg)

在这个项目中，我们一共打了两个tag，分别是：v0.0.1 和 module/tour/v0.0.1。这时候你可能会奇怪，为什么要打 `module/tour/v0.0.1` 这么“奇怪”的tag，这有什么用意吗？

其实是 Go modules 在同一个项目下多个模块的tag表现方式，其主要目录结构为：

```
mquote
├── go.mod
├── module
│   └── tour
│       ├── go.mod
│       └── tour.go
└── quote.go
```

可以看到在 `mquote` 这个项目的根目录有一个 go.mod 文件，而在 `module/tour` 目录下也有一个 go.mod 文件，其模块导入和版本信息的对应关系如下：

| tag               | 模块导入路径                          | 含义                                             |
| ----------------- | ------------------------------------- | ------------------------------------------------ |
| v0.0.1            | github.com/eddycjy/mquote             | mquote 项目的v 0.0.1 版本                        |
| module/tour/v0.01 | github.com/eddycjy/mquote/module/tour | mquote 项目下的子模块 module/tour 的 v0.0.1 版本 |

#### 导入主模块和子模块

结合上述内容，拉取主模块的话，还是照旧执行如下命令：

```
$ go get github.com/eddycjy/mquote@v0.0.1
go: finding github.com/eddycjy/mquote v0.0.1
go: downloading github.com/eddycjy/mquote v0.0.1
go: extracting github.com/eddycjy/mquote v0.0.1
```

如果是想拉取子模块，执行如下命令：

```
$ go get github.com/eddycjy/mquote/module/tour@v0.0.1
go: finding github.com/eddycjy/mquote/module v0.0.1
go: finding github.com/eddycjy/mquote/module/tour v0.0.1
go: downloading github.com/eddycjy/mquote/module/tour v0.0.1
go: extracting github.com/eddycjy/mquote/module/tour v0.0.1
```

我们将主模块和子模块的拉取进行对比，你会发现子模块的拉取会多出一步，它会先发现 `github.com/eddycjy/mquote/module`，再继续推算，最终拉取到 `module/tour`。

## Go Modules的导入路径说明

### 不同版本的导入路径

在前面的模块拉取和引用中，你会发现我们的模块导入路径就是 `github.com/eddycjy/mquote` 和  `github.com/eddycjy/mquote/module/tour`，似乎并没有什么特殊的。

其实不然，实际上 Go modules 在主版本号为 v0 和 v1 的情况下省略了版本号，而在主版本号为v2及以上则需要明确指定出主版本号，否则会出现冲突，其tag与模块导入路径的大致对应关系如下：

| tag    | 模块导入路径                 |
| ------ | ---------------------------- |
| v0.0.0 | github.com/eddycjy/mquote    |
| v1.0.0 | github.com/eddycjy/mquote    |
| v2.0.0 | github.com/eddycjy/mquote/v2 |
| v3.0.0 | github.com/eddycjy/mquote/v3 |

简单来讲，就是主版本号为 v0 和 v1 时，不需要在模块导入路径包含主版本的信息，而在 v1 版本以后，也就是 v2 起，必须要在模块的导入路径末尾加上主版本号，引用时就需要调整为如下格式：

```
import (
    "github.com/eddycjy/mquote/v2/example"
)
```

另外忽略主版本号 v0 和 v1 是强制性的（不是可选项），因此每个软件包只有一个明确且规范的导入路径。

### 为什么忽略v0和v1的主版本号

1. 导入路径中忽略 v1 版本的原因是：考虑到许多开发人员创建一旦到达 v1 版本便永不改变的软件包，这是官方所鼓励的，不认为所有这些开发人员在无意发布 v2 版时都应被迫拥有明确的 v1 版本尾缀，这将导致 v1 版本变成“噪音”且无意义。

2. 导入路径中忽略了 v0 版本的原因是：根据语义化版本规范，v0的这些版本完全没有兼容性保证。需要一个显式的 v0 版本的标识对确保兼容性没有多大帮助。

## Go Modules的语义化版本控制

我们不断地在 Go Modules 的使用中提到版本号，其实质上被称为“语义化版本”，假设我们的版本号是 v1.2.3，如下：

![image](https://image.eddycjy.com/6e556b628df36b1fd3800fb9d91a0d16.jpg)

其版本格式为“主版本号.次版本号.修订号”，版本号的递增规则如下：

1. 主版本号：当你做了不兼容的 API 修改。
2. 次版本号：当你做了向下兼容的功能性新增。
3. 修订号：当你做了向下兼容的问题修正。

假设你是先行版本号或特殊情况，可以将版本信息追加到“主版本号.次版本号.修订号”的后面，作为延伸，如下：

![image](https://image.eddycjy.com/b45438512cbb44015402da1a98190ac0.jpg)

至此我们介绍了 Go modules 所支持的两类版本号方式，在我们发布新版本打 tag 的时候，需要注意遵循，否则不遵循语义化版本规则的版本号都是无法进行拉取的。

## Go Modules的最小版本选择

现在我们已经有一个模块，也有发布的 tag，但是一个模块往往依赖着许多其它许许多多的模块，并且不同的模块在依赖时很有可能会出现依赖同一个模块的不同版本，如下图（来自Russ Cox）：

![image](https://image.eddycjy.com/7d509e8945fa31b7986369986c58e6f4.jpg)

在上述依赖中，模块 A 依赖了模块 B 和模块 C，而模块 B 依赖了模块 D，模块 C 依赖了模块 D 和 F，模块 D 又依赖了模块 E，而且同模块的不同版本还依赖了对应模块的不同版本。那么这个时候 Go modules 怎么选择版本，选择的是哪一个版本呢？

我们根据 proposal 可得知，Go modules 会把每个模块的依赖版本清单都整理出来，最终得到一个构建清单，如下图（来自Russ Cox）：

![image](https://image.eddycjy.com/2bd0bed89d9300c0aac24c7bc72a6307.jpg)

我们看到 rough list 和 final list，两者的区别在于重复引用的模块 D（v1.3、v1.4），其最终清单选用了模块 D 的 v1.4 版本，主要原因：

1. 语义化版本的控制：因为模块 D 的 v1.3 和 v1.4 版本变更，都属于次版本号的变更，而在语义化版本的约束下，v1.4 必须是要向下兼容 v1.3 版本，因此认为不存在破坏性变更，也就是兼容的。

2. 模块导入路径的规范：主版本号不同，模块的导入路径不一样，因此若出现不兼容的情况，其主版本号会改变，模块的导入路径自然也就改变了，因此不会与第一点的基础相冲突。

## go.sum文件要不要提交

理论上 go.mod 和 go.sum 文件都应该提交到你的 Git 仓库中去。

假设我们不上传 go.sum 文件，就会造成每个人执行 Go modules 相关命令，又会生成新的一份 go.sum，也就是会重新到上游拉取，再拉取时有可能就是被篡改过的了，会有很大的安全隐患，失去了与基准版本（第一个所提交的人，所期望的版本）的校验内容，因此 go.sum文件是需要提交。

## 总结

至此我们介绍了 Go modules 的前世今生、基本使用和在 Go modules 模式下 `go get` 命令的行为转换，同时我们对常见的多版本导入路径、语义化版本控制以及多模块的最小版本选择规则进行了大致的介绍。

Go modules 的成长和发展经历了一定的过程，如果你是刚接触的读者，直接基于 Go modules 的项目开始即可，如果既有老项目，那么是时候考虑切换过来了，Go1.14起已经准备就绪，并推荐你使用。

## 我的公众号

![image](https://image.eddycjy.com/25549b3f68cac5e89e92e1943d0babc2.jpeg)

## 参考

- [wiki/Modules](https://github.com/golang/go/wiki/Modules)
- [wiki/vgo](https://github.com/golang/go/wiki/vgo)
- [proposal](https://github.com/golang/go/issues/24301)
- [干货满满的 Go Modules 和 goproxy.cn](https://book.eddycjy.com/golang/talk/goproxy-cn.html)

================================================
FILE: content/posts/go/go-standards.md
================================================
---
title: "上帝视角看 “Go 项目标准布局” 之争"
date: 2021-09-13T23:34:23+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间 Go 语言社区有一件事情引爆了热议，那就是 `golang-standards/project-layout` 项目的 “Go 项目的标准布局” 之争。

没想到，五一假期，认真一看，这个 issues 已经提出将近一个月了，仍然在热议阶段，我想，咱们需要好好的聊聊这个话题。

煎鱼带你了解下的前因后果，再分享我的看法和业务真实情况。

背景
--

### 问题发生地

在 GitHub 上有一个项目 Spaghetti（github.com/adonovan/spaghetti），是 Go 软件包的一个依赖性分析工具。

该项目的目录结构如下：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/11b7f74aa3944e509c89bcbfc51a2c99~tplv-k3u1fbpfcp-zoom-1.image)

看上去并不复杂，代码量不多，文件平铺也不超过一屏，就是一个布局比较简单的项目。

有一位老哥提出了一个 PR，明确的期望该项目按照 `golang-standards/project-layout` 项目给出的 “标准” 布局来调整。：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/e0da59130ce94ee190d51491396d6919~tplv-k3u1fbpfcp-zoom-1.image)

我猜测该项目可能是因为把 Go、HTML、JS、PNG 和 go.mod 文件等摆在了一起，引起了该同学的一丝丝纠结，觉得比较乱？

### “标准布局“ 长什么样子

在 `golang-standards/project-layout` 项目中，其自称：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/55511ceb43cb48c59d0ce302783eec59~tplv-k3u1fbpfcp-zoom-1.image)

项目的组织名也是 "golang-standards"，其提供了一个基本的 Go 项目布局，精简展示如下：

```
project-layout
├── api
├── cmd
├── configs
├── docs
├── go.mod
├── init
├── internal
├── pkg
├── scripts
├── vendor
├── ...

```

*   /cmd：项目主要的应用程序。
    
*   /internal：私有的应用程序代码库，这些是不希望被其他人导入的代码。
    

*   应用程序实际的代码可以放在 /internal/app 目录（如：internal/app/myapp）。
    
*   应用程序的共享代码放在 /internal/pkg 目录（如：internal/pkg/myprivlib）中。
    

*   /pkg：外部应用程序可以使用的库代码（如：/pkg/mypubliclib）。其他项目将会导入这些库来保证项目可以正常运行。
    
*   /vendor：应用程序的依赖关系，可通过执行 `go mod vendor` 执行得到。
    
*   /configs：配置文件模板或默认配置。
    
*   /init：系统初始化（systemd、upstart、sysv）和进程管理（runit、supervisord）配置。
    
*   /scripts:：用于执行各种构建，安装，分析等操作的脚本。
    

更具体的布局介绍，大家可以参见 project-layout 项目的 README，其基本把方方面面的目录都考虑到了（人多力量大）。

由于内容过于长，因此就不一一展示了。

### Russ Cox 现身原因

不过很巧，该项目的作者是前 Google 员工，是 `gopl.io` 项目（5.1k stars）的作者。

在仅仅过去 23 分钟后，作为 GoTeam Leader 的 Russ Cox（@rsc）就现身，并提出新的 issue 表达出了反对意见：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/f72fcd999116477193c22430eb33c22f~tplv-k3u1fbpfcp-zoom-1.image)

在 `golang-standards/project-layout` 项目的 README 中有明确指出这不是官方的标准，有如下声称：

> > it is a set of common historical and emerging project layout patterns in the Go ecosystem.

Russ Cox 主要是对声称 "这是一套 Go 生态系统中常见的历史和新兴的项目布局模式" 这一说法表示了 “不准确” 的意见。

例如：Go 生态系统中的绝大多数包都不会将可导入的包放在 pkg 子目录中。更广泛地说，这里描述的只是非常复杂的工程项目，而 Go 的仓库往往要简单得多。

另外，不幸的是，这套项目布局在组织名字上被称作 "golang-standards"（Golang 标准） 提出来，实际上并非真的是官方标准，有误导的情况存在。

### Russ Cox 反对原因

在了解 project-layout 项目所提供的 “标准“ 项目布局和 Russ Cox 提出 issues 的背景后。

我们进一步了解 Russ Cox 认为**这不对**的根本考虑。project-layout 这个项目有两个问题：

*   它声称是 Go 标准（Go standards）的主办方，但实际上并非如此，因为这些标准绝非 Go 官方标准。
    
*   它提出的项目布局标准过于复杂，不是一个合理的标准。
    

Go 项目布局的标准是什么
-------------

提出这个 issues 后，出现了一大堆人追问 Russ Cox，到底何为 Go 项目的布局标准？

Russ Cox 给出了正式回应，一个可导入的 Go repo 的最小标准布局是：

*   在你的根目录下放一个 LICENSE 文件。
    
*   在你的根目录下放一个 go.mod 文件。
    
*   将 Go 代码放在 repo 中，放在根目录中，或者按照你认为合适的方式组织成一个目录树。
    

就这样了，这就是 "标准"，没有那么复杂。不需要像 project-layout 项目一样的布局。像是 Go 官方的 `golang.org/x` 仓库打破了 project-layout 所说的这些 "规则 "中的每一条。

Go 提案
-----

在经历了长时间的口水战后，已经有人在 Go 官方仓库提出希望释出相关的提案（proposal）：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/ada96a8647e04b38a340995ccf764156~tplv-k3u1fbpfcp-zoom-1.image)

猜测可能会有如下几种可能：

*   GitHub 项目 golang-standards/project-layout 愿意更名，不再自称 ”golang-standards“，不过可能性比较低，因为已经已多人提出，但作者没什么表示。
    
*   Go 官方正式提供 Go 标准项目布局的说明。
    
*   Go 官方不做约束，仅做表态，可能输出文章。
    

后续大家继续关注该提案，就可以知道发展了，传送门：issues #45861。

按照惯例，我猜测第三种可能性最大，因为很难有人可以提供所有开发者认可的标准，每个事业部、团队的喜好都可能有所不同。

总结
--

实际上，任何东西自称 “XX 标准”，在名气大后，都会带来一些问题。就像本文提到的 golang-standards/project-layout 项目一样。

换位思考一下，若你是某个项目的 Leader，某一天你的同事，被人拿着 “标准” 来建议修改时，说这是这个项目的 “标准”，会不会很奇妙？

无独有偶，我有一个朋友，他们公司早年只有一套 DDD 标准，本想统一。结果后面每一个介入 DDD 的业务同学，都认为前人不标准，每个人都自创了一套 DDD 标准。

总是会有小伙伴**想让定义绝对的 “标准”，又或是 “最佳实践”**。其实是难以定义的，最好的就是能够一个团队内形成基本共识，这里面牵扯到的不单单只有技术...

你对此有什么看法呢，**欢迎在评论区留言和大家一起交流**！

================================================
FILE: content/posts/go/go-tips-defer.md
================================================
---
title: "Go 群友提问：学习 defer 时很懵逼，这道不会做！"
date: 2021-04-05T16:10:51+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天在读者交流群里看到一位小伙伴，在向大家咨询 Go 相关的技术问题。
疑问是：“**各位大佬，我在学习 defer 遇到闭包的时候很懵逼，谁比较明白，能指点？**”

![](https://image.eddycjy.com/36e2b86b536909f265b84db24dcd80c6.jpg)

## 疑问

他的疑问是下面这道 Go 语言的 defer 题目，大家一起看看：

```
func main() {
	var whatever [6]struct{}
	for i := range whatever {
		defer func() {
			fmt.Println(i)
		}()
	}
}
```
请自己先想一下输出的结果答案是什么。

这位小伙伴按自己的理解后，认为应当输出 xx。但最终的输出结果，可能与其思考的有所偏差，一时想不通。

### 解惑

这段程序的输出结果是：

```
5
5
5
5
5
5
```

为什么全是 5，为什么不是 0, 1, 2, 3, 4, 5 这样的输出结果呢？

其根本原因是**闭包**所导致的，有两点原因：
- 在 `for` 循环结束后，局部变量 `i` 的值已经是 5 了，并且 `defer `的闭包是直接引用变量的 i。
- 结合`defer` 关键字的特性，可得知会在 `main` 方法主体结束后再执行。

结合上述，最终输出的结果是已经自增完毕的 5。

### 进一步思考

既然了解了为什么，我们再变形一下。再看看另外一种情况，代码如下：

```
func main() {
	var whatever [6]struct{}
	for i := range whatever {
		defer func(i int) {
			fmt.Println(i)
		}(i)
	}
}
```

与第一个案例不同，我们这回把变量 `i` 传了进去。那么他的输出结果是什么呢？

这段程序的输出结果是：

```
5
4
3
2
1
0
```

为什么是 5, 4, 3, 2, 1, 0 呢，为什么不是 0, 1, 2, 3, 4, 5？（难道煎鱼敲错了吗？）

其根本原因在于两点：
- 在 `for` 循环时，局部变量 `i` 已经传入进 `defer func` 中 ，属于值传递。其值在 `defer` 语句声明时的时候就已经确定下来了。
- 结合 `defer` 关键字的特性，是按**先进后出**的顺序来执行的。

结合上述，最终输出的结果是 5, 4, 3, 2, 1, 0。

## 下一个疑问

没过一会，这位小伙伴又有了新的感悟。抛出了新的示例问题，如下：

```
func f1() (r int) {
   defer func() {
      r++
   }()
   return 0
}

func f2() (r int) {
   t := 5
   defer func() {
      t = t + 5
   }()
   return t
}

func f3() (r int) {
   defer func(r int) {
      r = r + 5
   }(r)
   return 1
}
```

主函数：

```
func main() {
	println(f1())
	println(f2())
	println(f3())
}
```

请自己先想一下输出的结果答案是什么。


这段程序的输出结果是：

```
1
5
1
```

为什么是 1, 5, 1 呢，而不是 0, 10, 5，又或是其他答案？

欢迎大家在**下方评论区留言讨论和分享解题的思路**，一起思考和进步。

================================================
FILE: content/posts/go/go-tips-gmp-p.md
================================================
---
title: "Go 面试官：GMP 模型，为什么要有 P？"
date: 2021-04-05T16:15:20+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

最近金三银四，是面试的季节。在我的 Go 读者交流群里出现了许多小伙伴在讨论自己面试过程中所遇到的一些 Go 面试题。

今天的主角，是 Go 面试的万能题 GMP 模型的延伸题（疑问），那就是 ”**GMP 模型，为什么要有 P**？“

进一步推敲问题的背后，其实这个面试题本质是想问：”**GMP 模型，为什么不是 G 和 M 直接绑定就完了，还要搞多一个 P 出来，那么麻烦，为的是什么，是要解决什么问题吗**？“

这篇文章煎鱼就带你一同探索，GM、GMP 模型的变迁是因为什么原因。

## GM 模型

在 Go1.1 之前 Go 的调度模型其实就是 GM 模型，也就是没有 P。

今天带大家一起回顾过去的设计。

### 解密 Go1.0 源码

我们了解一个东西的办法之一就是看源码，和煎鱼一起看看 Go1.0.1 的[调度器源码](https://github.com/golang/go/blob/go1.0.1/src/pkg/runtime/proc.c)的核心关键步骤：

```c
static void
schedule(G *gp)
{
	...
	schedlock();
	if(gp != nil) {
		...
		switch(gp->status){
		case Grunnable:
		case Gdead:
			// Shouldn't have been running!
			runtime·throw("bad gp->status in sched");
		case Grunning:
			gp->status = Grunnable;
			gput(gp);
			break;
		}

	gp = nextgandunlock();
	gp->readyonstop = 0;
	gp->status = Grunning;
	m->curg = gp;
	gp->m = m;
	...
	runtime·gogo(&gp->sched, 0);
}
```

- 调用 `schedlock` 方法来获取全局锁。
- 获取全局锁成功后，将当前 Goroutine 状态从 Running（正在被调度） 状态修改为 Runnable（可以被调度）状态。
- 调用 `gput` 方法来保存当前 Goroutine 的运行状态等信息，以便于后续的使用；
- 调用 `nextgandunlock` 方法来寻找下一个可运行 Goroutine，并且释放全局锁给其他调度使用。
- 获取到下一个待运行的 Goroutine 后，将其的运行状态修改为 Running。
- 调用 `runtime·gogo` 方法，将刚刚所获取到的下一个待执行的 Goroutine 运行起来。

### 思考 GM 模型

通过对 Go1.0.1 的调度器源码剖析，我们可以发现一个比较有趣的点。那就是调度器本身（schedule 方法），在正常流程下，是不会返回的，也就是不会结束主流程。

![G-M模型简图](https://image.eddycjy.com/89f9533b4d59bacaa8fcadc47a690059.jpg)

他会不断地运行调度流程，GoroutineA 完成了，就开始寻找 GoroutineB，寻找到 B 了，就把已经完成的 A 的调度权交给 B，让 GoroutineB 开始被调度，也就是运行。

当然了，也有被正在阻塞（Blocked）的 G。假设 G 正在做一些系统、网络调用，那么就会导致 G 停滞。这时候 M（系统线程）就会被会重新放内核队列中，等待新的一轮唤醒。

### GM 模型的缺点

这么表面的看起来，GM 模型似乎牢不可破，毫无缺陷。但为什么要改呢？

在 2012 年时 Dmitry Vyukov 发表了文章《[Scalable Go Scheduler Design Doc](https://docs.google.com/document/d/1TTj4T2JO42uD5ID9e89oa0sLKhJYD0Y_kqxDv3I3XMw/edit)》，目前也依然成为各大研究 Go 调度器文章的主要对象，其在文章内讲述了整体的原因和考虑，下述内容将引用该文章。

当前（代指 Go1.0 的 GM 模型）的 Goroutine 调度器限制了用 Go 编写的并发程序的可扩展性，尤其是高吞吐量服务器和并行计算程序。

实现有如下的问题：
- 存在单一的全局 mutex（Sched.Lock）和集中状态管理：
    - mutex 需要保护所有与 goroutine 相关的操作（创建、完成、重排等），导致锁竞争严重。
- Goroutine 传递的问题：
    - goroutine（G）交接（G.nextg）：工作者线程（M's）之间会经常交接可运行的 goroutine。
    - 上述可能会导致延迟增加和额外的开销。每个 M 必须能够执行任何可运行的 G，特别是刚刚创建 G 的 M。
- 每个 M 都需要做内存缓存（M.mcache）：
    - 会导致资源消耗过大（每个 mcache 可以吸纳到 2M 的内存缓存和其他缓存），数据局部性差。
- 频繁的线程阻塞/解阻塞：
    - 在存在 syscalls 的情况下，线程经常被阻塞和解阻塞。这增加了很多额外的性能开销。

## GMP 模型

为了解决 GM 模型的以上诸多问题，在 Go1.1 时，Dmitry Vyukov 在 GM 模型的基础上，新增了一个 P（Processor）组件。并且实现了 Work Stealing 算法来解决一些新产生的问题。

![](https://image.eddycjy.com/fb4c6c92c93af3bc2dfc4f13dc167cdf.png)

GMP 模型，在上一篇文章《Go 群友提问：Goroutine 数量控制在多少合适，会影响 GC 和调度？》中已经讲解过了。

觉得不错的小伙伴可以关注一下，这里就不再复述了。

### 带来什么改变

加了 P 之后会带来什么改变呢？我们再更显式的讲一下。

- 每个 P 有自己的本地队列，大幅度的减轻了对全局队列的直接依赖，所带来的效果就是锁竞争的减少。而 GM 模型的性能开销大头就是锁竞争。

- 每个 P 相对的平衡上，在 GMP 模型中也实现了 Work Stealing 算法，如果 P 的本地队列为空，则会从全局队列或其他 P 的本地队列中窃取可运行的 G 来运行，减少空转，提高了资源利用率。

### 为什么要有 P

这时候就有小伙伴会疑惑了，如果是想实现本地队列、Work Stealing 算法，那为什么不直接在 M 上加呢，M 也照样可以实现类似的组件。为什么又再加多一个 P 组件？

结合 M（系统线程） 的定位来看，若这么做，有以下问题：

- 一般来讲，M 的数量都会多于 P。像在 Go 中，M 的数量默认是 10000，P 的默认数量的 CPU 核数。另外由于 M 的属性，也就是如果存在系统阻塞调用，阻塞了 M，又不够用的情况下，M 会不断增加。

- M 不断增加的话，如果本地队列挂载在 M 上，那就意味着本地队列也会随之增加。这显然是不合理的，因为本地队列的管理会变得复杂，且 Work Stealing 性能会大幅度下降。

-  M 被系统调用阻塞后，我们是期望把他既有未执行的任务分配给其他继续运行的，而不是一阻塞就导致全部停止。

因此使用 M 是不合理的，那么引入新的组件 P，把本地队列关联到 P 上，就能很好的解决这个问题。

## 总结

今天这篇文章结合了整个 Go 语言调度器的一些历史情况、原因分析以及解决方案说明。

”GMP 模型，为什么要有 P“ 这个问题就像是一道系统设计了解，因为现在很多人为了应对面试，会硬背 GMP 模型，或者是泡面式过了一遍。而理解其中真正背后的原因，才是我们要去学的要去理解。

知其然知其所以然，才可破局。

================================================
FILE: content/posts/go/go-tips-goroutineid.md
================================================
---
title: "Go 群友提问：进程、线程都有 ID，为什么 Goroutine 没有 ID？"
date: 2021-04-05T16:14:14+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

最近金三银四，是面试的季节。在我的 Go 读者交流群里出现了许多小伙伴在讨论自己面试过程中所遇到的一些 Go 面试题。

今天的主角，是大家在既有语言基础的情况下，学 Goroutine 时会容易纠结的一点。就是 “**进程、线程都有 ID，为什么 Goroutine 没有 GoroutineID？**”。

这是为什么呢，怎么做那些跨协程处理呢？

## GoroutineID 是什么

我们要知道，为什么大家会下意识的想去要 GoroutineID，下面引用 Go 语言圣经中的表述：

>> 在大多数支持多线程的操作系统和程序语言中，当前的线程都有一个独特的身份（ID），并且这个身份信息可以以一个普通值的形式被很容易地获取到，典型的可以是一个 integer 或者指针值。这种情况下我们做一个抽象化的 thread-local storage（线程本地存储，多线程编程中不希望其它线程访问的内容）就很容易，只需要以线程的 ID 作为 key 的一个 map 就可以解决问题，每一个线程以其 ID 就能从中获取到值，且和其它线程互不冲突。

也就在常规的进程、线程中都有其 ID 的概念，我们可以在程序中通过 ID 来获取其他进程、线程中的数据，甚至是传输数据。就像一把钥匙一样，有了他干啥都可以。

GoroutineID 的概念也是类似的，也就是协程的 ID。我们下意识的就期望通过协程 ID 来进行跨协程的操作。

但，在 Go 语言中 GoroutineID 并没有显式获取的办法，这就要打个大大的疑惑了。

## 为什么没有 GoroutineID

为什么在 Go 语言中没有 GoroutineID 呢，是从一开始就没有的，还是，这样子设计的原因是什么呢？

其实 Go 语言在以前是有暴露方法去获取 GoroutineID 的，但在 Go1.4 后就把该方法给隐藏起来了，不建议大家使用。

也就是明面上没有 GoroutineID，是一个有意而为之的行为。原因是：**根据以往的经验，认为 thread-local storage 存在被滥用的可能性，且带来许多不必要的复杂度**。

简单来讲，Andrew Gerrand 的回答是 ”**thread-local storage 的成本远远超过了它们的收益。它们只是不适合 Go 语言**。”

### 潜在的问题

- 当 Goroutine 消失时：
    - 它的 Goroutine 本地存储将不会被 GC 化。 (你可以得到 goid 的当前的 Goroutine，但你不能得到所有运行的 Goroutine 的列表)

- 如果处理程序自己产生了新的 Goroutine 怎么办？ 
    - 新的 Goroutine 失去了对既有的 Goroutine 本地存储。虽然你可以保证自己的代码不会产生其他的 Goroutine。
    - 一般来说，你不能确保标准库或任何第三方代码不会这样做。
- Go 应用程序的复杂度和心智负担等上升。

### 滥用的场景

有一个对外提供 HTTP 服务的 Go 应用，也就是 Web Server。Go HTTP Server 都是采取每次请求新起一个协程的方式。


假设可以通过 GoroutineID 进行跨协程操纵，那么就有可能出现我的 Goroutine，不一定是由 “我” 自己决定的。可能其他正在处理的 GoroutineB 悄悄摸摸的改了我这个 GoroutineA 的行为。

这就有可能导致一个灾难问题，就是出问题时，你不知道是谁动了你的奶酪。查起问题来简直就是一个灾难。

若是自己维护的模块清楚还起码知道这事，假设你的前同事刚好离职了，你又在熟悉代码，一出问题。这锅那是死死的扣在了你的头上了。

## 如何获取 GoroutineID

刚刚我们提到是在明面上把 GoroutineID 给隐藏了，那暗面呢，是不是有其他办法可以获取到？

答案是：可以的。

通过骇客代码的方式可以获取到。在 Go 语言的标准库 [http/2 的 gotrack ](https://github.com/golang/net/blob/master/http2/gotrack.go) 中，就有提供如下获取方法：

```golang
func main() {
    go func() {
        fmt.Println("脑子进煎鱼了的 GoroutineID：", curGoroutineID())
    }()

    time.Sleep(time.Second)
}

func curGoroutineID() uint64 {
    bp := littleBuf.Get().(*[]byte)
    defer littleBuf.Put(bp)
    b := *bp
    b = b[:runtime.Stack(b, false)]
    // Parse the 4707 out of "goroutine 4707 ["
    b = bytes.TrimPrefix(b, goroutineSpace)
    i := bytes.IndexByte(b, ' ')
    if i < 0 {
        panic(fmt.Sprintf("No space found in %q", b))
    }
    b = b[:i]
    n, err := parseUintBytes(b, 10, 64)
    if err != nil {
        panic(fmt.Sprintf("Failed to parse goroutine ID out of %q: %v", b, err))
    }
    return n
}

var littleBuf = sync.Pool{
    New: func() interface{} {
        buf := make([]byte, 64)
        return &buf
    },
}

var goroutineSpace = []byte("goroutine ")
```

输出结果为：

```
脑子进煎鱼了的 GoroutineID： 18
```

结合 `curGoroutineID` 方法来看，可以通过对 Go 运行时的分析，也就是 `runtime.Stack` 从而得到 GoroutineID。

其作用，更多的是对进行跟踪和调试作用居多。因为官方并没有根据 GoroutineID 提供一系列跨协程操纵的方法。

也有如下开源库可以用于获取 GoroutineID（不过均多年未维护了）：

- [davecheney/junk](github.com/davecheney/junk)
- [jtolio/gls](https://github.com/jtolio/gls)
- [tylerstillwater/gls](https://github.com/tylerstillwater/gls)

Go 团队的 Dave Cheney 对其所开源的 GoroutineID 库，评价：“If you use this package, you will go straight to hell.”：

![davecheney/junk](https://image.eddycjy.com/5f67767b9f8d0be030294d8a2ffb8b83.jpg)

也就是 “如果你使用这个包，你会直接下地狱。“，非常猛了，深深地劝退大家使用。

## 日常在哪里常见

如果大家经常做救火队长，去排查 Go 工程中的问题，例如：错误堆栈信息、PProf 性能分析等调试信息。

因此经常看到 GoroutineID，也就是 “`goroutine ####` […]”。

我们所看到的 `####` 就是真实的 GoroutineID，剩余的信息就是一些堆栈跟踪和错误描述了。

## 应该使用 GoroutineID 吗？

从结果来看，肯定是不推荐使用 GoroutineID 了。毕竟没有什么特别的好处，Go 团队也是反对的。

所以一般都会直接回答 ”无法获取 GoroutineID“，应当跟从语言设计理念，使用 [Share Memory By Communicating](https://blog.golang.org/codelab-share) 来实现跨协程的操纵会更合理。

## 总结

今天这篇文章我们根据 GoroutineID 的历史，作用，原因，骇客方法进行了逐一梳理，摸索了下里面究竟为何物。

进程、线程、协程的对比是一个面试中常被拿出来问的话题，而 GoroutineID 就是其中一点，这涉及到整个全局上的设计考虑。

你又是否遇到过 GoroutineID 使用和疑问的场景呢，欢迎大家一起留言讨论。

================================================
FILE: content/posts/go/go-tips-goroutineloop.md
================================================
---
title: "Go 面试官：单核 CPU，开两个 Goroutine，其中一个死循环，会怎么样？"
date: 2021-04-05T16:17:23+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

最近金三银四，是面试的季节。在我的 Go 读者交流群里出现了许多小伙伴在讨论自己面试过程中所遇到的一些 Go 面试题。

今天的男主角，是与 Go 工程师有调度相关的知识，那就是 “**单核 CPU，开两个 Goroutine，其中一个死循环，会怎么样？**”

**请在此处默念自己心目中的答案**，再往和煎鱼一起研讨一波 Go 的技术哲学。

## 问题定义

针对这个问题，我们需要把问题剖开来看看，其具有以下几个元素：
- 运行 Go 程序的计算机只有一个单核 CPU。
- 两个 Goroutine 在运行。
- 一个 Goroutine 死循环。

根据这道题的题意，可大致理解其想要问的是 Go 调度相关的一些知识理解。

### 单核 CPU

第一个要点，就是要明确 “计算机只有一个单核 CPU” 这一个变量定义，对 Go 程序会产生什么影响，否则很难继续展开。

既然明确涉及 Goroutine，这里就会考察到你对 Go 的调度模型 GMP 的基本理解了。

从单核 CPU 来看，最大的影响就是 GMP 模型中的 P，因为 P 的数量默认是与 CPU 核数（GOMAXPROCS）保持一致的。

- G：Goroutine，实际上我们每次调用 `go func` 就是生成了一个 G。
- P：Processor，处理器，一般 P 的数量就是处理器的核数，可以通过 `GOMAXPROCS` 进行修改。
- M：Machine，系统线程。

这三者交互实际来源于 Go 的 M: N 调度模型。也就是 M 必须与 P 进行绑定，然后不断地在 M 上循环寻找可运行的 G 来执行相应的任务。

### Goroutine 受限

第二个要点，就是 Goroutine 的数量和运行模式都是受限的。有两个 Goroutine，一个 Goroutine 在死循环，另外一个在正常运行。

这可以理解为 Main Goroutine + 起了一个新 Goroutine 跑着死循环，因为本身 main 函数就是一个主协程在运行着，没毛病。

需要注意的是，Goroutine 里跑着死循环，也就是时时刻刻在运行着 “业务逻辑”。这块需要与单核 CPU 关联起来，**考虑是否会一直阻塞住，把整个 Go 进程运行给 hang 住了**？

注： 但若是在现场面试，可以先枚举出这种场景，诠释清楚后。再补充提问面试官，是否这类场景？

### Go 版本的问题

第三个要点，是一个隐性的拓展点。如果你是一个老 Go 粉，经常关注 Go 版本的更新情况（至少大版本），则应该会知道 Go 的调度是会变动的（会在后面的小节讲解）。

因此**本文这个问题，在不同的 Go 语言版本中，结果可能会是不一样**的。但是面试官并没有指出，这里就需要考虑到：
1. 面试官故意不指出，等着你指出。
2. 面试官没留意到这块，没想那么多。
3. 面试官自己都不知道这块的 “新” 知识，他的知识可能还是老的。

如果你注意到了，是一个小亮点，说明你在这块有一定的知识积累。

## 实战演练

在刚刚过去的 3s 中，你已经把上面的考量都在大脑中过了一遍。接下来我们正式进入实战演练，构造一个例子：

```golang
// Main Goroutine 
func main() {
    // 模拟单核 CPU
    runtime.GOMAXPROCS(1)
    
    // 模拟 Goroutine 死循环
    go func() {
        for {
        }
    }()

    time.Sleep(time.Millisecond)
    fmt.Println("脑子进煎鱼了")
}
```

在上面的例子中，我们通过以下方式达到了面试题所需的目的：
- 设置 `runtime.GOMAXPROCS` 方法模拟了单核 CPU 下只有一个 P 的场景。
- 运行一个 Goroutine，内部跑一个 for 死循环，达到阻塞运行的目的。
- 运行一个 Goroutine，主函数（main）本身就是一个 Main Goroutine。

思考一下：**这段程序是否会输出 ”脑子进煎鱼了“ 呢，为什么**？

答案是：
- 在 Go1.14 前，不会输出任何结果。
- 在 Go1.14 及之后，能够正常输出结果。

## 为什么

这是怎么回事呢，这两种情况分别对应了什么原因和标准，Go 版本的变更有带来了什么影响？

### 不会输出任何结果

显然，这段程序是有一个 Goroutine 是正在执行死循环，也就是说他肯定无法被抢占。

这段程序中更没有涉及主动放弃执行权的调用（runtime.Gosched），又或是其他调用（可能会导致执行权转移）的行为。
因此这个 Goroutine 是没机会溜号的，只能一直打工...

那为什么主协程（Main Goroutine）会无法运行呢，其实原因是会优先调用休眠，但由于单核 CPU，其只有唯一的 P。唯一的 P 又一直在打工不愿意下班（执行 for 死循环，被迫无限加班）。

因此主协程永远没有机会呗调度，所以这个 Go 程序自然也就一直阻塞在了执行死循环的 Goroutine 中，永远无法下班（执行完毕，退出程序）。

### 正常输出结果

那为什么 Go1.14 及以后的版本，又能正常输出了呢？

主要还是**在 Go1.14 实现了基于信号的抢占式调度**，以此来解决上述一些仍然无法被抢占解决的场景。

主要原理是Go 程序在启动时，会在 `runtime.sighandler` 方法注册并且绑定 `SIGURG` 信号：

```golang
func mstartm0() {
	...
	initsig(false)
}

func initsig(preinit bool) {
	for i := uint32(0); i < _NSIG; i++ {
		...
		setsig(i, funcPC(sighandler))
	}
}
```

绑定相应的 `runtime.doSigPreempt` 抢占方法：

```golang
func sighandler(sig uint32, info *siginfo, ctxt unsafe.Pointer, gp *g) {
    ...
    if sig == sigPreempt && debug.asyncpreemptoff == 0 {
        // 执行抢占
        doSigPreempt(gp, c)
    }
}
```

同时在调度的 `runtime.sysmon` 方法会调用 `retake` 方法处理一下两种场景：
- 抢占阻塞在系统调用上的 P。
- 抢占运行时间过长的 G。

该方法会检测符合场景的 P，当满足上述两个场景之一。就会发送信号给 M， M 收到信号后将会休眠正在阻塞的 Goroutine，调用绑定的信号方法，并进行重新调度。以此来解决这个问题。

注：在 Go 语言中，sysmon 会用于检测抢占。sysmon 是 Go 的 Runtime 的系统检测器，sysmon 可进行 forcegc、netpoll、retake 等一系列骚操作（via @xiaorui）。

## 总结

在这篇文章中，我们针对 ”单核 CPU，开两个 Goroutine，其中一个死循环，会怎么样？“ 这个问题进行了展开剖析。

针对不同 Go 语言版本，不同程序逻辑的表现形式都不同，但背后的基本原理都是与 Go 调度模型和抢占有关。

你是否有在这一块遇到问题呢，欢迎大家在留言区评论和交流。

================================================
FILE: content/posts/go/go-tips-goroutinenums.md
================================================
---
title: "Go 群友提问：Goroutine 数量控制在多少合适，会影响 GC 和调度？"
date: 2021-04-05T16:08:18+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天在读者交流群里看到一位小伙伴，发出了一个致命提问，那就是：“**单机的 goroutine 数量控制在多少比较合适？**”。

也许你和群内小伙伴第一反应一样，会答复 “控制多少，我觉得没有定论”。

紧接着延伸出了更进一步的疑惑：“**goroutine 太多了会影响 gc 和调度吧，主要是怎么预算这个数是合理的呢？**”

这是本文要进行探讨的主体，因此本文的结构会是先探索基础知识，再一步步揭开，深入理解这个问题。

## Goroutine 是什么

Go 语言作为一个新生编程语言，其令人喜爱的特性之一就是 goroutine。Goroutine 是一个由 Go 运行时管理的轻量级线程，一般称其为 “协程”。

```
go f(x, y, z)
```

操作系统本身是无法明确感知到 Goroutine 的存在的，Goroutine 的操作和切换归属于 “用户态” 中。

Goroutine 由特定的调度模式来控制，以 “多路复用” 的形式运行在操作系统为 Go 程序分配的几个系统线程上。

同时创建 Goroutine 的开销很小，初始只需要 2-4k 的栈空间。Goroutine 本身会根据实际使用情况进行自伸缩，非常轻量。

```
func say(s string) {
	for i := 0; i < 9999999; i++ {
		time.Sleep(100 * time.Millisecond)
		fmt.Println(s)
	}
}

func main() {
	go say("煎鱼")
	say("你好")
}

```

人称可以开几百几千万个的协程小霸王，是 Go 语言的得意之作之一。

## 调度是什么

既然有了用户态的代表 Goroutine，操作系统又看不到他。必然需要有某个东西去管理他，才能更好的运作起来。

这指的就是 Go 语言中的调度，最常见、面试最爱问的 GMP 模型。因此接下来将会给大家介绍一下 Go 调度的基础知识和流程。

下述内容摘自煎鱼和 p 神写的《Go 语言编程之旅》中的章节内容。

### 调度基础知识

Go scheduler 的主要功能是针对在处理器上运行的 OS 线程分发可运行的 Goroutine，而我们一提到调度器，就离不开三个经常被提到的缩写，分别是：

- G：Goroutine，实际上我们每次调用 `go func` 就是生成了一个 G。
- P：Processor，处理器，一般 P 的数量就是处理器的核数，可以通过 `GOMAXPROCS` 进行修改。
- M：Machine，系统线程。

这三者交互实际来源于 Go 的 M: N 调度模型。也就是 M 必须与 P 进行绑定，然后不断地在 M 上循环寻找可运行的 G 来执行相应的任务。

### 调度流程

我们以 GMP 模型的工作流程图进行简单分析，官方图如下:

![](https://image.eddycjy.com/fb4c6c92c93af3bc2dfc4f13dc167cdf.png)

1. 当我们执行 `go func()` 时，实际上就是创建一个全新的 Goroutine，我们称它为 G。
2. 新创建的 G 会被放入 P 的本地队列（Local Queue）或全局队列（Global Queue）中，准备下一步的动作。需要注意的一点，这里的 P 指的是创建 G 的 P。
3. 唤醒或创建 M 以便执行 G。
4. 不断地进行事件循环
5. 寻找在可用状态下的 G 进行执行任务
6. 清除后，重新进入事件循环

在描述中有提到全局和本地这两类队列，其实在功能上来讲都是用于存放正在等待运行的 G，但是不同点在于，本地队列有数量限制，不允许超过 256 个。

并且在新建 G 时，会优先选择 P 的本地队列，如果本地队列满了，则将 P 的本地队列的一半的 G 移动到全局队列。

这可以理解为调度资源的共享和再平衡。

### 窃取行为

我们可以看到图上有 steal 行为，这是用来做什么的呢，我们都知道当你创建新的 G 或者 G 变成可运行状态时，它会被推送加入到当前 P 的本地队列中。

其实当 P 执行 G 完毕后，它也会 “干活”，它会将其从本地队列中弹出 G，同时会检查当前本地队列是否为空，如果为空会随机的从其他 P 的本地队列中尝试窃取一半可运行的 G 到自己的名下。

官方图如下：

![](https://image.eddycjy.com/6fde3925fd4172a1c89938018bd2d7b5.png)

在这个例子中，P2 在本地队列中找不到可以运行的 G，它会执行 `work-stealing` 调度算法，随机选择其它的处理器 P1，并从 P1 的本地队列中窃取了三个 G 到它自己的本地队列中去。

至此，P1、P2 都拥有了可运行的 G，P1 多余的 G 也不会被浪费，调度资源将会更加平均的在多个处理器中流转。

## 有没有什么限制

在前面的内容中，我们针对 Go 的调度模型和 Goroutine 做了一个基本介绍和分享。

接下来我们回到主题，思考 “goroutine 太多了，会不会有什么影响”。

在了解 GMP 的基础知识后，我们要知道**在协程的运行过程中，真正干活的 GPM 又分别被什么约束**？

煎鱼带大家分别从 GMP 来逐步分析。

### M 的限制

第一，要知道**在协程的执行中，真正干活的是 GPM 中的哪一个**？

那势必是 M（系统线程） 了，因为 G 是用户态上的东西，最终执行都是得映射，对应到 M 这一个系统线程上去运行。

那么 M 有没有限制呢？

答案是：有的。在 Go 语言中，**M 的默认数量限制是 10000**，如果超出则会报错：

```
GO: runtime: program exceeds 10000-thread limit
```

通常只有在 Goroutine 出现阻塞操作的情况下，才会遇到这种情况。这可能也预示着你的程序有问题。

若确切是需要那么多，还可以通过 `debug.SetMaxThreads` 方法进行设置。

### G 的限制

第二，那 G 呢，Goroutine 的创建数量是否有限制？

答案是：没有。但**理论上会受内存的影响**，假设一个 Goroutine 创建需要 4k（via @GoWKH）：

- 4k * 80,000 = 320,000k ≈ 0.3G内存
- 4k * 1,000,000 = 4,000,000k ≈ 4G内存

以此就可以相对计算出来一台单机在通俗情况下，所能够创建 Goroutine 的大概数量级别。

注：Goroutine 创建所需申请的 2-4k 是需要连续的内存块。

### P 的限制

第三，那 P 呢，P 的数量是否有限制，受什么影响？

答案是：有限制。**P 的数量受环境变量 `GOMAXPROCS` 的直接影响**。

环境变量 `GOMAXPROCS` 又是什么？
在 Go 语言中，通过设置 `GOMAXPROCS`，用户可以调整调度中中 P（Processor）的数量。

另一个重点在于，与 P 相关联的的 M（系统线程），是需要绑定 P 才能进行具体的任务执行的，因此 P 的多少会影响到 Go 程序的运行表现。

P 的数量基本是受本机的核数影响，没必要太过度纠结他。

那 P 的数量是否会影响 Goroutine 的数量创建呢？

答案是：不影响。且 Goroutine 多了少了，P 也该干嘛干嘛，不会带来灾难性问题。

## 何为之合理

在介绍完 GMP 各自的限制后，我们回到一个重点，就是 “Goroutine 数量怎么预算，才叫合理？”。

“合理” 这个词，是需要看具体场景来定义的，可结合上述对 GPM 的学习和了解。
得出：
- M：有限制，默认数量限制是 10000，可调整。
- G：没限制，但受内存影响。
- P：受本机的核数影响，可大可小，不影响 G 的数量创建。

Goroutine 数量在 MG 的可控限额以下，多个把个、几十个，少几个其实没有什么影响，就可以称其为 “合理”。

## 真实情况

在真实的应用场景中，没法如此简单的定义。如果你 Goroutine：
- 在频繁请求 HTTP，MySQL，打开文件等，那假设短时间内有几十万个协程在跑，那肯定就不大合理了（可能会导致  too many files open）。
- 常见的 Goroutine 泄露所导致的 CPU、Memory 上涨等，还是得看你的 Goroutine 里具体在跑什么东西。

还是得看 Goroutine 里面跑的是什么东西。

## 总结

在这篇文章中，分别介绍了 Goroutine、GMP、调度模型的基本知识，针对如下问题进行了展开：
- 单机的 goroutine 数量控制在多少比较合适？
- goroutine 太多了会影响 gc 和调度吧，主要是怎么预算这个数是合理的呢？

单机的 goroutine 数量只要控制在限额以下的，都可以认为是 “合理”。

真实场景得看具体里面跑的是什么，跑的如果是 “资源怪兽”，只运行几个 Goroutine 都可能可以跑死。因此想定义 “预算”，就得看跑的什么了。






================================================
FILE: content/posts/go/go-tips-interface.md
================================================
---
title: "Go 面试官：Go interface 的一个 “坑” 及原理分析"
date: 2021-04-05T16:12:59+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天在读者交流群里看到一位小伙伴，针对 interface 的使用有了比较大的疑惑。

无独有偶，我也在网上看到有小伙伴在 Go 面试的时候被问到了：


![来自网上博客的截图](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/36d7ecb0da9e4b32a493dedce6ebc691~tplv-k3u1fbpfcp-watermark.image)

今天特意分享出来让大家避开这个坑。

## 例子一

第一个例子，如下代码：


```golang
func main() {
    var v interface{}
    v = (*int)(nil)
    fmt.Println(v == nil)
}
```

你觉得输出结果是什么呢？

答案是：

```
false
```
为什么不是 `true`。明明都已经强行置为 `nil` 了。是不是 Go 编译器有问题？

## 例子二

第二个例子，如下代码：

```golang
func main() {
    var data *byte
    var in interface{}

    fmt.Println(data, data == nil)
    fmt.Println(in, in == nil)

    in = data
    fmt.Println(in, in == nil)
}
```

你觉得输出结果是什么呢？

答案是：

```
<nil> true
<nil> true
<nil> false
```

这可就更奇怪了，为什么刚刚声明出来的 `data` 和 `in` 变量，确实是输出结果是 `nil`，判断结果也是 `true`。

怎么把变量 `data` 一赋予给变量 `in`，世界就变了？输出结果依然是 `nil`，但判定却变成了 `false`。

和上面的第一个例子结果类似，真是神奇。

## 原因

interface 判断与想象中不一样的根本原因是，interface 并不是一个指针类型，虽然他看起来很像，以至于误导了不少人。

我们钻下去 interface，interface 共有两类数据结构：

![](https://imgkr2.cn-bj.ufileos.com/560dcab5-e436-4a2c-bfee-6eba6faee1d2.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=HF1wka8F9MTc%252FVCTrMjhASpeeE4%253D&Expires=1615900476)

- `runtime.eface` 结构体：表示不包含任何方法的空接口，也称为 empty interface。
- `runtime.iface` 结构体：表示包含方法的接口。

看看这两者相应的底层数据结构：

```golang
type eface struct {
    _type *_type
    data  unsafe.Pointer
}

type iface struct {
    tab  *itab
    data unsafe.Pointer
}
```

你会发现 interface 不是单纯的值，而是**分为类型和值**。

所以传统认知的此 nil 并非彼 nil，**必须得类型和值同时都为 nil 的情况下，interface 的 nil 判断才会为 true**。

## 解决办法

与其说是解决方法，不如说是委婉的破局之道。在不改变类型的情况下，方法之一是利用反射（reflect），如下代码：

```golang
func main() {
    var data *byte
    var in interface{}

    in = data
    fmt.Println(IsNil(in))
}

func IsNil(i interface{}) bool {
    vi := reflect.ValueOf(i)
    if vi.Kind() == reflect.Ptr {
        return vi.IsNil()
    }
    return false
}
```

利用反射来做 nil 的值判断，在反射中会有针对 interface 类型的特殊处理，最终输出结果是：true，达到效果。

其他方法的话，就是改变原有的程序逻辑，例如：
- 对值进行 nil 判断，再返回给 interface 设置。
- 返回具体的值类型，而不是返回 interface。

## 总结

Go interface 是 Go 语言中最常用的类型之一，大家用惯了 `if err != nil` 就很容易顺手就踩进去了。

建议大家要多留个心眼，如果对 interface 想要有更进一步的了解，可以看看我的这篇深入解析的文章：《一文吃透 Go 语言解密之接口 interface》。


================================================
FILE: content/posts/go/go-tips-lenstr.md
================================================
---
title: "问个 Go 问题，字符串 len 为 0 和 字符串为空 ，有啥区别？"
date: 2021-04-05T16:09:14+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天在微信群看到几位大佬在讨论一个问题： ”**字符串 len == 0 和 字符串 == "" ，有啥区别**？“

这是一个比较小的细节点，同时也勾起了我的好奇心，因此今天这篇文章就和大家一起研究一下他们两者有没有区别，谁的性能更好一些？

## 测试方法

在测试的方法中，我们分别声明了 `Test1` 和 `Test2` 方法：

```
func Test1() bool {
	var v string
	if v == "" {
		return true
	}
	return false
}

func Test2() bool {
	var v string
	if len(v) == 0 {
		return true
	}
	return false
}
```

在方法内部仅做了简单的变量类型声明，分别以 字符串 == "" 和 字符串 len == 0 为判断依据。

## 测试用例

编写两个方法的 Benchmark，用于后续的性能测试：

```
func BenchmarkTest1(b *testing.B) {
	for i := 0; i < b.N; i++ {
		Test1()
	}
}

func BenchmarkTest2(b *testing.B) {
	for i := 0; i < b.N; i++ {
		Test2()
	}
}
```

## 结果分析

```
$ go test --bench=. -benchmem
goos: darwin
goarch: amd64
BenchmarkTest1-4   	1000000000	         0.305 ns/op	       0 B/op	       0 allocs/op
BenchmarkTest2-4   	1000000000	         0.305 ns/op	       0 B/op	       0 allocs/op
PASS
ok  	_/Users/eddycjy/go-application/awesomeProject/tests	0.688s
```

从多次测试的结果来看，两者比较：
- 性能几乎没有区别，甚至可以出现一模一样的情况。
- 均不涉及内存申请和操作，均为 0/op。说明变量并不是声明了，就有初始化动作的，这块 Go 编译器有做优化。

结果上居然是一样的。根据曹大的提示，我们可以进一步看一下两者的汇编代码，看看具体区别在哪里：

```
$ go tool compile -S main.go
"".main STEXT nosplit size=1 args=0x0 locals=0x0
	0x0000 00000 (main.go:3)	TEXT	"".main(SB), NOSPLIT|ABIInternal, $0-0
	0x0000 00000 (main.go:3)	FUNCDATA	$0, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
	0x0000 00000 (main.go:3)	FUNCDATA	$1, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
	0x0000 00000 (main.go:5)	RET
	0x0000 c3                                               .
go.cuinfo.packagename. SDWARFINFO dupok size=0
	0x0000 6d 61 69 6e                                      main
""..inittask SNOPTRDATA size=24
	0x0000 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00 00  ................
	0x0010 00 00 00 00 00 00 00 00                          ........
gclocals·33cdeccccebe80329f1fdbee7f5874cb SRODATA dupok size=8
	0x0000 01 00 00 00 00 00 00 00   
```

无论是 `len(v) == 0`，又或是 `v == ""` 的判断，其编译出来的汇编代码都是完全一致的。可以明确 Go 编译器在这块做了明确的优化，大概率是直接比对了。

大家有没有其他的看法和拓展呢，欢迎一起来学习和交流。




================================================
FILE: content/posts/go/go-tips-sturct.md
================================================
---
title: "Go 面试官：Go 结构体是否可以比较，为什么？"
date: 2021-04-05T16:16:00+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

最近金三银四，是面试的季节。在我的 Go 读者交流群里出现了许多小伙伴在讨论自己面试过程中所遇到的一些 Go 面试题。

今天的男主角，是 Go 工程师的必修技能，也是极容易踩坑的地方，就是 “**Go 面试题：Go 结构体（struct）是否可以比较？**”

如果可以比较，是为什么？如果不可以比较，又是为什么？

**请在此处默念自己心目中的答案**，再往和煎鱼一起研讨一波 Go 的技术哲学。

## 结构体是什么

在 Go 语言中有个基本类型，开发者们称之为结构体（struct）。是 Go 语言中非常常用的，基本定义：

```golang
type struct_variable_type struct {
    member definition
    member definition
    ...
    member definition
}
```

简单示例：

```golang
package main

import "fmt"

type Vertex struct {
    Name1 string
    Name2 string
}

func main() {
    v := Vertex{"脑子进了", "煎鱼"}
    v.Name2 = "蒸鱼"
    fmt.Println(v.Name2)
}
```

输出结果：

```
蒸鱼
```

这部分属于基础知识，因此不再过多解释。如果看不懂，建议重学 Go 语言语法基础。

## 比较两下

### 例子一

接下来正式开始研讨 Go 结构体比较的问题，第一个例子如下：

```golang
type Value struct {
    Name   string
    Gender string
}

func main() {
    v1 := Value{Name: "煎鱼", Gender: "男"}
    v2 := Value{Name: "煎鱼", Gender: "男"}
    if v1 == v2 {
        fmt.Println("脑子进煎鱼了")
        return
    }

    fmt.Println("脑子没进煎鱼")
}
```

我们声明了两个变量，分别是 v1 和 v2。其都是 `Value` 结构体的实例化，是同一个结构体的两个实例。

他们的比较结果是什么呢，是输出 ”脑子进煎鱼了“，还是 ”脑子没进煎鱼“？

输出结果：

```
脑子进煎鱼了
```

最终输出结果是 ”脑子进煎鱼了“，初步的结论是可以结构体间比较的。皆大欢喜，那这篇文章是不是就要结束了？

当然不是...很多人都会踩到这个 Go 语言的坑，**真实情况是结构体是可比较，也不可比较的**，不要误入歧途了，这是一个非常 "有趣" 的现象。

### 例子二

接下来继续改造上面的例子，我们在原本的结构体中增加了指针类型的引用。

第二个例子如下：

```golang
type Value struct {
    Name   string
    Gender *string
}

func main() {
    v1 := Value{Name: "煎鱼", Gender: new(string)}
    v2 := Value{Name: "煎鱼", Gender: new(string)}
    if v1 == v2 {
        fmt.Println("脑子进煎鱼了")
        return
    }

    fmt.Println("脑子没进煎鱼")
}
```

这段程序输出结果是什么呢，我们猜测一下，变量依然是同一结构体的两个实例，值的赋值方式和内容都是一样的，是否应当输出 “脑子进煎鱼了”？

答案是：脑子没进煎鱼。

### 例子三

我们继续不信邪，试试另外的基本类型，看看结果是不是还是相等的。

第三个例子如下：

```golang
type Value struct {
    Name   string
    GoodAt []string
}

func main() {
    v1 := Value{Name: "煎鱼", GoodAt: []string{"炸", "煎", "蒸"}}
    v2 := Value{Name: "煎鱼", GoodAt: []string{"炸", "煎", "蒸"}}
    if v1 == v2 {
        fmt.Println("脑子进煎鱼了")
        return
    }

    fmt.Println("脑子没进煎鱼")
}
```

这段程序输出结果是什么呢？

答案是：

```
# command-line-arguments
./main.go:15:8: invalid operation: v1 == v2 (struct containing []string cannot be compared)
```
程序运行就直接报错，IDE 也提示错误，一只煎鱼都没能输出出来。

### 例子四

那不同结构体，相同的值内容呢，能否进行比较？

第四个例子：

```golang
type Value1 struct {
    Name string
}

type Value2 struct {
    Name string
}

func main() {
    v1 := Value1{Name: "煎鱼"}
    v2 := Value2{Name: "煎鱼"}
    if v1 == v2 {
        fmt.Println("脑子进煎鱼了")
        return
    }

    fmt.Println("脑子没进煎鱼")
}
```

显然，会直接报错：

```
# command-line-arguments
./main.go:18:8: invalid operation: v1 == v2 (mismatched types Value1 and Value2)
```

那是不是就完全没法比较了呢？并不，我们可以借助强制转换来实现：

```golang
	if v1 == Value1(v2) {
		fmt.Println("脑子进煎鱼了")
		return
	}
```

这样程序就会正常运行，且输出 “脑子进煎鱼了”。当然，若是不可比较类型，依然是不行的。

## 为什么

为什么 Go 结构体有的比较就是正常，有的就不行，甚至还直接报错了。难道是有什么 “潜规则” 吗？

在 Go 语言中，Go 结构体有时候并不能直接比较，当其基本类型包含：slice、map、function 时，是不能比较的。若强行比较，就会导致出现例子中的直接报错的情况。

而指针引用，其虽然都是 `new(string)`，从表象来看是一个东西，但其具体返回的地址是不一样的。

因此若要比较，则需改为：

```golang
func main() {
    gender := new(string)
    v1 := Value{Name: "煎鱼", Gender: gender}
    v2 := Value{Name: "煎鱼", Gender: gender}
    ...
}
```

这样就可以保证两者的比较。如果我们被迫无奈，被要求一定要用结构体比较怎么办？

这时候可以使用反射方法 `reflect.DeepEqual`，如下：

```golang
func main() {
    v1 := Value{Name: "煎鱼", GoodAt: []string{"炸", "煎", "蒸"}}
    v2 := Value{Name: "煎鱼", GoodAt: []string{"炸", "煎", "蒸"}}
    if reflect.DeepEqual(v1, v2) {
        fmt.Println("脑子进煎鱼了")
        return
    }

    fmt.Println("脑子没进煎鱼")
}
```

这样子就能够正确的比较，输出结果为 “脑子进煎鱼了”。

例子中所用到的反射比较方法 `reflect.DeepEqual` 常用于判定两个值是否深度一致，其规则如下：

- 相同类型的值是深度相等的，不同类型的值永远不会深度相等。
- 当数组值（array）的对应元素深度相等时，数组值是深度相等的。
- 当结构体（struct）值如果其对应的字段（包括导出和未导出的字段）都是深度相等的，则该值是深度相等的。
- 当函数（func）值如果都是零，则是深度相等；否则就不是深度相等。
- 当接口（interface）值如果持有深度相等的具体值，则深度相等。
- ...

更具体的大家可到 `golang.org/pkg/reflect/#DeepEqual` 进行详细查看：

![reflect.DeepEqual 完整说明](https://image.eddycjy.com/aefb19ae4bce5bbbada39244141bfd68.jpg)

该方法对 Go 语言中的各种类型都进行了兼容处理和判别，由于这不是本文的重点，因此就不进一步展开了。

## 总结

在本文中，我们针对 Go 语言的结构体（struct）是否能够比较进行了具体例子的展开和说明。

其本质上还是对 Go 语言基本数据类型的理解问题，算是变形到结构体中的具体进一步拓展。

不知道你有没有在 Go 结构体吃过什么亏呢，欢迎在下方评论区留言和我们一起交流和讨论。

================================================
FILE: content/posts/go/go-tips-timer-memory.md
================================================
---
title: "Go 内存泄露之痛，这篇把 Go timer.After 问题根因讲透了！"
date: 2021-04-05T16:16:47+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天在公众号分享了一篇 Go timer 源码解析的文章《难以驾驭的 Go timer，一文带你参透计时器的奥秘》。

在评论区有小伙伴提到了经典的 `timer.After` 泄露问题，希望我能聊聊，这是一个不能不知的一个大 “坑”。

今天这篇文章煎鱼就带大家来研讨一下这个问题。

## timer.After

今天是男主角是Go 标准库 time 所提供的 `After` 方法。函数签名如下：

```golang
func After(d Duration) <-chan Time 
```

该方法可以在一定时间（根据所传入的 Duration）后主动返回 `time.Time` 类型的 channel 消息。

在常见的场景下，我们会基于此方法做一些计时器相关的功能开发，例子如下：

```golang
func main() {
    ch := make(chan string)
    go func() {
        time.Sleep(time.Second * 3)
        ch <- "脑子进煎鱼了"
    }()

    select {
    case _ = <-ch:
    case <-time.After(time.Second * 1):
        fmt.Println("煎鱼出去了，超时了！！！")
    }
}
```

在运行 1 秒钟后，输出结果：

```
煎鱼出去了，超时了！！！
```

上述程序在在运行 1 秒钟后将触发 `time.After` 方法的定时消息返回，输出了超时的结果。

## 坑在哪里

从例子来看似乎非常正常，也没什么 “坑” 的样子。难道是 `timer.After` 方法的虚晃一枪？

我们再看一个不像是有问题例子，这在 Go 工程中经常能看见，只是大家都没怎么关注。

代码如下：

```golang
func main() {
    ch := make(chan int, 10)
    go func() {
        in := 1
        for {
            in++
            ch <- in
        }
    }()
    
    for {
        select {
        case _ = <-ch:
            // do something...
            continue
        case <-time.After(3 * time.Minute):
            fmt.Printf("现在是：%d，我脑子进煎鱼了！", time.Now().Unix())
        }
    }
}
```

在上述代码中，我们构造了一个 `for+select+channel` 的一个经典的处理模式。

同时在 `select+case` 中调用了 `time.After` 方法做超时控制，避免在 `channel` 等待时阻塞过久，引发其他问题。

看上去都没什么问题，但是细心一看。在运行了一段时间后，粗暴的利用 `top` 命令一看：

![运行了一会后，10+GB](https://image.eddycjy.com/4ad756d034cbbe7e7a19d9b4eb0c4843.jpg)

我的 Go 工程的内存占用竟然已经达到了 10+GB 之高，并且还在持续增长，非常可怕。

在所设置的超时时间到达后，Go 工程的内存占用似乎一时半会也没有要回退下去的样子，这，到底发生了什么事？

## 为什么

抱着一脸懵逼的煎鱼，我默默的掏出我早已埋好的 PProf，这是 Go 语言中最强的性能分析剖析工具，在我出版的 《Go 语言编程之旅》特意有花量章节的篇幅大面积将讲解过。

在 Go 语言中，PProf 是用于可视化和分析性能分析数据的工具，PProf 以 profile.proto 读取分析样本的集合，并生成报告以可视化并帮助分析数据（支持文本和图形报告）。

我们直接用 `go tool pprof` 分析 Go 工程中函数内存申请情况，如下图：

![PProf](https://image.eddycjy.com/c9552708ee112bceef4ac80f1ead50bd.jpg)

从图来分析，可以发现是不断地在调用 `time.After`，从而导致计时器 `time.NerTimer` 的不断创建和内存申请。

这就非常奇怪了，因为我们的 Go 工程里只有几行代码与 `time` 相关联：

```golang
func main() {
    ...
    for {
        select {
        ...
        case <-time.After(3 * time.Minute):
            fmt.Printf("现在是：%d，我脑子进煎鱼了！", time.Now().Unix())
        }
    }
}
```

由于 Demo 足够的小，我们相信这就是问题代码，但原因是什么呢？

原因在于 `for`+`select`，再加上 `time.After` 的组合会导致内存泄露。因为 `for`在循环时，就会调用都 `select` 语句，因此在每次进行 `select` 时，都会重新初始化一个全新的计时器（Timer）。

我们这个计时器，是在 3 分钟后才会被触发去执行某些事，但重点在于计时器激活后，却又发现和 `select` 之间没有引用关系了，因此很合理的也就被 GC 给清理掉了，因为没有人需要 “我” 了。

![](https://image.eddycjy.com/b84d7d95fc2ca3d9688ae56461449512.jpg)

要命的还在后头，被抛弃的 `time.After` 的定时任务还是在时间堆中等待触发，在定时任务未到期之前，是不会被 GC 清除的。

![](https://image.eddycjy.com/8c2b0ebbce7d8e0d4432bb7c81a50c6e.jpg)

但很可惜，他 “永远” 不会到期了，也就是为什么我们的 Go 工程内存会不断飙高，其实是 `time.After` 产生的内存孤儿们导致了泄露。

## 解决办法

既然我们知道了问题的根因代码是不断的重复创建 `time.After`，又没法完整的走完释放的闭环，那解决办法也就有了。

改进后的代码如下：

```golang
func main() {
    timer := time.NewTimer(3 * time.Minute)
    defer timer.Stop()
    
    ...
    for {
        select {
        ...
        case <-timer.C:
            fmt.Printf("现在是：%d，我脑子进煎鱼了！", time.Now().Unix())
        }
    }
}
```

经过一段时间的摸鱼后，再使用 PProf 进行采集和查看：

![PProf](https://image.eddycjy.com/bed36b48fb6e75d690208e1b1b149369.jpg)

Go 进程的各项指标正常，完好的解决了这个内存泄露的问题。

## 总结

在今天这篇文章中，我们介绍了标准库 `time` 的基本常规使用，同时针对 Go 小伙伴所提出的 `time.After` 方法的使用不当，所导致的内存泄露进行了重现和问题解析。

其根因就在于 Go 语言时间堆的处理机制和常规 `for`+`select`+`time.After` 组合的下意识写法所导致的泄露。

突然想起我有一个朋友在公司里有看到过类似的代码...

不知道你在日常工作中有没有遇到过相似的问题呢，欢迎留言区评论和交流。



================================================
FILE: content/posts/go/go-typeparams-master.md
================================================
---
title: "令人激动！Go 泛型代码合入 master（附尝鲜方法）"
date: 2021-04-05T16:06:50+08:00
images:
tags: 
  - go
---

大家好，我是慢一拍的后方记者煎鱼。

按照先前官方和文章的说法，Go 泛型预计是在 Go1.18 正式释出。

![](https://imgkr2.cn-bj.ufileos.com/8971e01e-75f8-47c2-b9d3-f6b0ebd85d0d.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=8eKquOL0aM7GzJXegZUzGkOmLPg%253D&Expires=1614491040)


在 GopherCon 2020 Go Team AMA 时，要在今年底要能有生产环境的试用版上线，这是 rsc 所提出的一个管理目标。

## 转折点

近期出现了一个新的转折点，能够让大家在主干分支（master）上就能享受到泛型的功能。

![](https://imgkr2.cn-bj.ufileos.com/3acc09a4-d5a2-49e7-b272-b2fa1571f589.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=zXcEIWPbc%252BUFBDmTyYrRVywwKuI%253D&Expires=1614491656)

而 master 分支对应了 Go1.17 的版本。因此未来将可以在 Go1.17 使用到泛型，这是一个比较惊喜的事情。

## 原因

这件事情为什么会突然发生呢？一切都得从背景说起。原本 Go 泛型是一直在 [dev.typeparams](https://github.com/golang/go/tree/dev.typeparams) 分支上进行研讨和开发。

由于泛型不是简单的一两个模块的代码变更，而是涉及大量的代码变更。

因此需要经常保持与 master 分支的代码同步（近两个月共 20+ 次），会涉及代码冲突/合并的处理，且对于一些冲突的模块他们也不熟悉，所以期望迁移到 master 分支上进行开发。

## 如何不影响既有功能

这类提前放入主版本的操作，在 Go 语言中并不少见。像是现在所见的 `GO111MODULE`，早期的 `GO15VENDOREXPERIMENT` 都有些这么个味道。都是逐步入场，分阶段使用，等确定成熟、完善后再渐渐去掉。

因此本次泛型也采取了这种方法，按照提案，目前使用的是 `-G` 标识做为泛型的开关。

计划如下：

- `-G=0`：继续使用传统的类型检查器。
- `-G=1`：使用 type2，但不支持泛型。
- `-G=2`：使用 type2，支持泛型。

在完成 types2 的错误和现有的错误的开发协调后，计划在 Go 1.17 将 `-G=1` 设置为默认值。

未来也许可以在 Go 1.18 中放弃对 `-G=0` 的支持，这样后续在默认启用 `-G=2` 上会变得更容易。

## 在 Go1.17 尝鲜

在 Go1.17 尝鲜，也就意味着需要拉取 Go 语言的 master 分支的代码，Go1.17 现在正处于开发阶段：

![](https://imgkr2.cn-bj.ufileos.com/8690e590-08d0-416b-b7c0-76a3cd9fbd2b.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=YDlj2rmds9pT8iLgaho3cITFCuw%253D&Expires=1614498690)

我们可以通过 `gotip` 来达到下载 master 分支代码的目的：

```
$ go get golang.org/dl/gotip
$ gotip download
From https://go.googlesource.com/go
 * branch            master     -> FETCH_HEAD
   44361140c0..d9fd38e68b master     -> origin/master
Previous HEAD position was 44361140c0 embed: update docs for proposal tweaks
...
```

在拉取完毕后可以执行 `gotip version` 查看所拉取的版本（commit-id）：

```
$ gotip version
go version devel +d9fd38e68b Sat Feb 27 03:03:29 2021 +0000 darwin/amd64
```

在确定 `gotip` 正常后，我们就可以编写泛型的示例代码了，如下：

```
func Print[T any](s []T) {
	for _, v := range s {
		fmt.Print(v)
	}
}

func main() {
	Print([]string{"脑子进, ", "煎鱼了\n"})
}
```

如果执行像往常那样执行，是会直接提示无法识别泛型的一些标识符：

```
$ gotip run main.go 
# command-line-arguments
./main.go:7:6: missing function body
./main.go:7:11: syntax error: unexpected [, expecting (
```

结合上文的解析，我们需要指定 `-G` 标识，就可以运行了。如下：

```
$ gotip run -gcflags=all=-G=3 main.go 
# command-line-arguments
./main.go:7:6: internal compiler error: Cannot export a generic function (yet): Print
```

显然，正确的走进泛型的逻辑里去了，虽然愉快的报错了，但 Matthew Dempsky 表示这很正常，毕竟 Go 泛型还在开发阶段。

可能会有的小伙伴注意到，`-G` 指定的是 3，与前文所述不符。这与早期的编码有关：

![](https://imgkr2.cn-bj.ufileos.com/4599daf1-36ef-4c4a-bdf7-33bcbe7ac1cb.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=S9zQAMxyQpdxryZN%252FrwkYOmqDI4%253D&Expires=1614499432)

已经提了 CL 变更，只是代码冲突了，待解决。

## 总结

Go 语言的泛型开发计划已经比较明确。首先合入 master 分支，再逐步完成开发，逐步开放。

再进行 `-G` 默认值的调整，最后在泛型完善后就默认开启，把 `-G` 标识彻底去掉。

细品，与 Go modules 的方向是不是差不多。一开始 `GO111MODULE` 需要手动开启 `on`（也就是默认 `off`），再到 Go1.16 `GO111MODULE` 默认为 `on`。

以此完成了一个正反馈的循环，逐步开放，接受社区反馈和开发调整。

结论，**Go 泛型指日可待了**。


================================================
FILE: content/posts/go/go-why-path.md
================================================
---
title: "意见征集：Go1 要不要移除 GOPATH？"
date: 2021-04-05T16:02:34+08:00
images:
tags: 
  - go
---

大家好，我是在打自己脸的后方记者煎鱼。

前几天我发表了文章《意见征集：Go1 要不要移除 GOPATH？》。
本次投票共有 592 人参与了投票。
结果如下：

![](https://static01.imgkr.com/temp/d10e1354bc9d43c68439fb71d8935270.png)

绝大部分人支持移除 GOPATH，但建议保留的人依然占相当一部分。

## 最新进展

在近几天，在 go issues 上有人提出了新的提案：《proposal: cmd/go: maintain 'classic' vendor behaviour》。

该提案正式向 Go 官方提出了我们上一篇文章有提到的两点：
1. Go 历史项目的维护问题。
2. Go1 兼容性保证的许诺。

摘选一部分核心观点给大家看看。

## 新的提案

从 Go1.17 开始，Go1.17 就将 GOPATH 从编译器工具链中移除 `GO111MODULE` 标识。

其依据如下：

![](https://static01.imgkr.com/temp/bf314e0979b7481681c6293ee60715c3.png)

重点在于执行 `-mod=vendor` 命令时，其会忽略主模块根目录以外位置的软件目录，**这意味着在 go mod 之前设计和编写的应用程序不能再编译（指的历史项目问题）**。

提案本身并不是要求要保持 GOPATH 代码解析 1:1 的说法，而是希望能够允许项目代码通过其他的方式在移除 GOPATH 后也能正常运行，有其他方式能够导入（不需要转成 Go mod）。

另外最后提到删除 GOPATH 这样的代码解析能力，**与下面这段摘自 go1compat 文档的精神不一致**：

>> It is intended that programs written to the Go 1 specification will continue to compile and run correctly, unchanged, over the lifetime of that specification. At some indefinite point, a Go 2 specification may arise, but until that time, Go programs that work today should continue to work even as future "point" releases of Go 1 arise (Go 1.1, Go 1.2, etc.).

指出直接移除 GOPATH 可能违反 Go1 兼容性保证的精神，带来历史项目的工作量。

## 相爱相杀

无独有偶，前几天我和欧神（@changkun）就讨论过 Go1 兼容性保证（go1compat）的问题，我也是认为违反了该精神保证，这次行为不是很合理。

但...欧神重读 《Go 1 and the Future of Go Programs》后，也就是我们俗称的 Go1 兼容性保证。发现了以下亮点：

![](https://static01.imgkr.com/temp/aa47a80786814576b5a5b091d8244127.png)

在工具链中提到，**Go 语言的工具链（编译器、链接器、构建工具等）仍然正在积极开发中，可能会改变行为，也就是不在兼容性保护的范围内**。

我们回到主角身上，GOPATH 是什么：GOPATH 定义的是软件的构建形式而不是编译的条件，归属于工具链里。

因此其实**移除 GOPATH 并不违反 Go1 兼容性保证**，因为他不在保障范围内。

注：感谢欧神的探讨和释疑，在此推荐欧神的大作《[Go 语言原本](https://golang.design/under-the-hood/ "Go 语言原本")》。

## 总结

目前该[提案](https://github.com/golang/go/issues/44519 "提案")已经进入 proposal review meeting 日程了，很快就会有决策了，在这里我们就不进行过多的新方案探讨。

现实场景中依赖 GOPATH 的历史项目确实存在，使用什么方法更低成本、合理的让既有项目能够正常运行将会是一个讨论重点。

接下来煎鱼将会跟踪这个提案，新的消息会继续同步。毕竟我是利益相关者（有依赖 GOPATH 的项目)...

欢迎大家一起来讨论各种可能性！

================================================
FILE: content/posts/go/go1.16-1.md
================================================
---
title: "Go1.16 即将正式发布，以下变更你需要知道"
date: 2021-02-11T16:13:15+08:00
images:
tags: 
  - go
---

大家好，我是正在努力学习的煎鱼。

在前几天，Go1.16rc1 抢先发布了。结合常规的 28 发布规律，其将会在 2021.02 月份左右发布正式版本。

![](https://imgkr2.cn-bj.ufileos.com/417219ea-578e-48f0-8a83-84544000a698.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=mbLHd49lXRyOoY%252FlyamD5YnGagw%253D&Expires=1612064951)

这次 Go1.16 也带来了一些新特性或变更。那么作为一个 Gopher，想必不能错过这次的更新。

![](https://imgkr2.cn-bj.ufileos.com/4161e3cd-9f66-4f3f-8f68-91f3ba496c18.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=CwpOhSJnk70gEkTF8ITIxC58PoM%253D&Expires=1612074386)

今天这篇文章将会带大家了解一下 Go1.16 的几个需要关注的特性。

### 废弃 io/ioutil

Go 官方认为 io/ioutil 这个包的定义不明确且难以理解。所以 Russ Cox 在 2020.10.17 提出了废弃 io/ioutil 的提案。

大致变更如下：
- Discard => io.Discard
- NopCloser => io.NopCloser
- ReadAll => io.ReadAll
- ReadDir => os.ReadDir
- ReadFile => os.ReadFile
- TempDir => os.MkdirTemp
- TempFile => os.CreateTemp
- WriteFile => os.WriteFile

与此同时大家也不需要担心存在破坏性变更，因为有 Go1 兼容性的保证，在 Go1 中 io/ioutil 还会存在，只变更内部的方法调用：

```
func ReadAll(r io.Reader) ([]byte, error) {
    return io.ReadAll(r)
}

func ReadFile(filename string) ([]byte, error) {
    return os.ReadFile(filename)
}
```

大家在后续也可以改改调用习惯。

### 支持静态资源嵌入

如果我们希望把静态文件编译进 Go 的二进制文件的话，在以往需要借助 go-bindata/go-bindata 这类第三方开源库来实现。

而从 Go1.16 起，通过 `go:embed` 就可以快速实现这个功能：

```
import _ "embed"

//go:embed hello.txt
var s string
print(s)
```

通过对变量 `s` 声明 `go:embed` 指令，使其在编译时读取当前目录下的 `hello.txt` 文件。

最终变量 `s` 就会输出 `hello.txt` 文件中的字符串内容。 

### 新增 io/fs 的支持 

新增了标准库 io/fs，正式将文件系统相关的基础接口抽象到了该标准库中。

以前的话大多是在 `os` 标准库中，这一步抽离更进一步的抽象了文件树的接口。在后续的版本中，大家可以优先考虑使用 `io/fs` 标准库。

### 调整切片扩容策略

Go1.16 以前的 slice 的扩容条件是 `len`，在最新的代码中，已经改为了以 `cap` 属性作为基准：

```
  // src/runtime/slice.go
	if cap > doublecap {
		newcap = cap
	} else {
		// 这是以前的代码：if old.len < 1024 {
		// 下面是 Go1.16rc1 的代码
		if old.cap < 1024 {
			newcap = doublecap
		}
```

以官方的 test case 为例：

```
func main() {
	const N = 1024
	var a [N]int
	x := cap(append(a[:N-1:N], 9, 9))
	y := cap(append(a[:N:N], 9))
	println(cap(x), cap(y))
}
```

在 Go1.16 以前输出 2048, 1280。在 Go1.16 及以后输出 1280, 1280，保证了两种的一致。

### 支持 Apple Silicon M1

众所周知，最新版本的 Mac 采用了新的 64 位 ARM 架构，因此在 Go1.16 后正式支持了 `GOOS=darwin` 和 `GOARCH=arm64`。

而相应的先前用于 iOS 端口的，将改为 `GOOS=ios` 和 `GOARCH=arm64`。

同时 Apple M1 能不能很好的跑好 Go 语言程序也是各大微信群爱讨论的问题，在 GoLand 上：

![图来自网络，路过微信群看见](https://static01.imgkr.com/temp/960978d546694a5c94ca2af70e44c83c.png)

需要注意，GoLand 的一些给你要到后续的新版本才可以使用。

### 调整 Go modules 策略

从 Go1.16 起，Go modules 的环境变量 `GO111MODULE `默认开关将为 `on`，不再是之前是 `auto` 了。

还在使用 GOPATH，或 Go modules 没切全的同学这一块需要特别注意。

### 新增 GODEBUG inittrace

GODEBUG 新增 inittrace 指令，可以用于 `init` 方法的排查：

```
$ GODEBUG=inittrace=1 go run main.go 
```

输出结果：

```
init internal/bytealg @0.008 ms, 0 ms clock, 0 bytes, 0 allocs
init runtime @0.059 ms, 0.026 ms clock, 0 bytes, 0 allocs
init math @0.19 ms, 0.001 ms clock, 0 bytes, 0 allocs
init errors @0.22 ms, 0.004 ms clock, 0 bytes, 0 allocs
init strconv @0.24 ms, 0.002 ms clock, 32 bytes, 2 allocs
init sync @0.28 ms, 0.003 ms clock, 16 bytes, 1 allocs
init unicode @0.44 ms, 0.11 ms clock, 23328 bytes, 24 allocs
...
```

主要作用是 init 函数跟踪的支持，以用于 init 调试和启动时间的概要分析，算是一个 GODEBUG 的补充功能点。

## 简化结构体标签

在 Go 语言的结构体中，我们常常会因为各种库的诉求，需要对结构体的 `tag` 设置标识。

如果像是以前，量比较多就会变成：

```
type MyStruct struct {
  Field1 string `json:"field_1,omitempty" bson:"field_1,omitempty" xml:"field_1,omitempty" form:"field_1,omitempty" other:"value"`
}
```

但在 Go1.16 及以后，就可以通过合并的方式：

```
type MyStruct struct {
  Field1 string `json,bson,xml,form:"field_1,omitempty" other:"value"`
}
```

方便和简洁了不少。

## 总结

在本次 Go1.16 中带来了不少小优化和新的特性支持。离 Go1.18 的泛型又近了一步。

另外在本次新版本中，像是 `template` 支持跨行：

```
{{"hello" |
   printf}}
```

又或是 Linux 的默认内存管理策略下又从 MADV_FREE 改回了 MADV_DONTNEED 策略，大家在新版本中不再需要设置：

```
GODEBUG=madvdontneed=1
```

大家若有需求都可以进一步去了解，现在新版本的功能特性已经锁定，基本尘埃落定。

传送门：https://tip.golang.org/doc/go1.16。





================================================
FILE: content/posts/go/go1.16-2.md
================================================
---
title: "Go1.16 新特性：快速上手 Go embed"
date: 2021-02-11T16:13:19+08:00
images:
tags: 
  - go
---

在以前，很多从其他语言转过来 Go 语言的同学会问到，或是踩到一个坑。就是以为 Go 语言所打包的二进制文件中会包含配置文件的联同编译和打包。

![](https://imgkr2.cn-bj.ufileos.com/f59a06c7-2fa1-41f4-901c-990f7dd7d715.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=werBc5OkLhKUh0JhpYpcAtl3etA%253D&Expires=1612147306)


结果往往一把二进制文件挪来挪去，就无法把应用程序运行起来了。因为无法读取到静态文件的资源。

无法将静态资源编译打包进二进制文件的话，通常会有两种解决方法：
- 第一种是识别这类静态资源，是否需要跟着程序走。
- 第二种就是考虑将其打包进二进制文件中。

第二种情况的话，Go 以前是不支持的，大家就会去借助各种花式的开源库，例如：go-bindata/go-bindata 来实现。

但从在 Go1.16 起，Go 语言自身正式支持了该项特性，今天我们将通过这篇文章快速了解和学习这项特性。

## 基本使用

演示代码：

```
import _ "embed"

//go:embed hello.txt
var s string

func main() {
	print(s)
}
```
我们首先在对应的目录下创建了 `hello.txt` 文件，并且写入文本内容 “吃煎鱼”。

在代码中编写了最为核心的 `//go:embed hello.txt` 注解。注解的格式很简单，就是 `go:embed` 指令声明，外加读取的内容的地址，可支持相对和绝对路径。

输出结果：

```
吃煎鱼
```

读取到静态文件中的内容后自动赋值给了变量 `s`，并且在主函数中成功输出。

而针对其他的基础类型，Go embed 也是支持的：

```
//go:embed hello.txt
var s string

//go:embed hello.txt
var b []byte

//go:embed hello.txt
var f embed.FS

func main() {
	print(s)
	print(string(b))

	data, _ := f.ReadFile("hello.txt")
	print(string(data))
}
```

输出结果：

```
吃煎鱼
吃煎鱼
吃煎鱼
```

我们同时在一个代码文件中进行了多个 embed 的注解声明。

并且针对 string、slice、byte、fs 等多种类型进行了打包，也不需要过多的处理，非常便利。

## 拓展用法

除去基本用法完，embed 本身在指令上也支持多种变形：

```
//go:embed hello1.txt hello2.txt
var f embed.FS

func main() {
	data1, _ := f.ReadFile("hello1.txt")
	fmt.Println(string(data1))

	data2, _ := f.ReadFile("hello2.txt")
	fmt.Println(string(data2))
}
```
在指定 `go:embed` 注解时可以一次性多个文件来读取，并且也可以一个变量多行注解：

```
//go:embed hello1.txt 
//go:embed hello2.txt
var f embed.FS
```

也可以通过在注解中指定目录 `helloworld`，再对应读取文件：

```
//go:embed helloworld
var f embed.FS

func main() {
	data1, _ := f.ReadFile("helloworld/hello1.txt")
	fmt.Println(string(data1))

	data2, _ := f.ReadFile("helloworld/hello2.txt")
	fmt.Println(string(data2))
}
```

同时既然能够支持目录读取，也能支持贪婪模式的匹配：

```
//go:embed helloworld/*
var f embed.FS
```

可能会有小伙伴注意到，`embed.FS` 也能调各类文件系统的接口，其实本质是 `embed.FS` 实现了 `io/fs` 接口。

## 只读属性

在 embed 所提供的 FS 中，我们可以发现其都是打开和只读方法：

```
type FS
    func (f FS) Open(name string) (fs.File, error)
    func (f FS) ReadDir(name string) ([]fs.DirEntry, error)
    func (f FS) ReadFile(name string) ([]byte, error)
```

根据此也可以确定 embed 所打包进二进制文件的内容只允许读取，不允许变更。

更抽象来讲就是在编译期就确定了 embed 的内容，在运行时不允许修改，保证了一致性。

## 总结

通过 Go1.16 正式提供的 embed 特性，可以实现原生就支持静态资源文件的嵌入。整体如下：

- 在功能上：能够将静态资源嵌入二进制文件中，在运行时可以打开和读取相关的打包后的静态文件。
- 在安全上：是在编译期编译嵌入，在运行时不支持修改。
- 在使用上：
    - 支持单文件读取：`go:embed hello.txt`。
    - 支持多文件读取：`go:embed hello1.txt`、`go:embed hello2.txt`。
    - 支持目录读取：`go:embed helloworld`。
    - 支持贪婪匹配：`go:embed helloworld/*`。

总的来讲，Go1.16 embed 特性很好的填补了 Go 语言在打包静态文件资源的一块原生空白领域。同时也说明了 Go 官方的确在不断地吸收社区的一些良好的想法和经验。

================================================
FILE: content/posts/go/go1.16-3.md
================================================
---
title: "Go1.16 新特性：详解内存管理机制的变更，你需要了解"
date: 2021-02-11T16:13:20+08:00
images:
tags: 
  - go
---


大家好，我是正在学习如何蒸鱼的煎鱼。

在前面 Go1.16 特性介绍的文章中我们有提到，从 v1.16 起，Go 在 Linux 下的默认内存管理策略会从`MADV_FREE` 改回 `MADV_DONTNEED` 策略。

这时候可能至少分两拨小伙伴，分别是：

- 知道是什么，被这个问题 “折磨“ 过的，瞬间眼前一亮。
- 不知道是什么，出现了各种疑惑了，这说的都是些什么。

## 灵魂拷问

你有没有以下的疑问，或者是否清楚：

- 文中所说的 `MADV_FREE` 是什么？
- 文中所说的 `MADV_DONTNEED` 是什么？
- 为什么特指 Go 语言的 Linux 环境？
- 为什么是说从 `MADV_FREE`改回 `MADV_DONTNEED`？

在今天这篇文章中我们都将进一步的展开和说明，让我们一同来了解这个改来改去的内存机制到底是何物。

## madvise 爱与恨

在 Linux 系统中，在 Go Runtime 中通过系统调用 `madvise(addr, length, advise)` 方法，能够告诉内核如何处理从 addr 开始的 length 字节。

重点之一就是 ”如何处理“，在 Linux 下 Go 语言中目前支持两种策略，分别是：

- MADV_FREE：内核会在进程的页表中将这些页标记为“未分配”，从而进程的 RSS 就会变小。OS 后续可以将对应的物理页分配给其他进程。
- MADV_DONTNEED：内核只会在页表中将这些进程页面标记为可回收，在需要的时候才回收这些页面。

## 所带来的影响

Go 语言官方恰好就在 2019 年的 Go1.12 做了如下调整。

- Go1.12 以前。
- Go.12-Go1.15.


### Go1.12 以前

Go Runtime 在 Linux 上默认使用的是 `MADV_DONTNEED` 策略。

```
  // 没有任何奇奇怪怪的判断
	madvise(v, n, _MADV_DONTNEED)
```

从整体效果来看，进程 RSS 可以下降的比较快，但从性能效率上来看差点。


### Go1.12-Go1.15

当前 Linux 内核版本 >=4.5 时，Go Runtime 在 Linux 上默认使用了性能更为高效的 MADV_FREE 策略。

```
	var advise uint32
	if debug.madvdontneed != 0 {
		advise = _MADV_DONTNEED
	} else {
		advise = atomic.Load(&adviseUnused)
	}
	if errno := madvise(v, n, int32(advise)); advise == _MADV_FREE && errno != 0 {
		// MADV_FREE was added in Linux 4.5. Fall back to MADV_DONTNEED if it is
		// not supported.
		atomic.Store(&adviseUnused, _MADV_DONTNEED)
		madvise(v, n, _MADV_DONTNEED)
	}
```

从整体效果来看，进程RSS 不会立刻下降，要等到系统有内存压力了才会释放占用，RSS 才会下降。

## 带来的副作用

故事往往不是那么的美好，显然在 Go1.12 起针对 `madvise` 的 `MADV_FREE` 策略的调整非常 “片面”。

![来自社区小伙伴](https://static01.imgkr.com/temp/5b82f6e181bd406db94e31bca3a4b2ab.png)

结合社区里所遇到的案例可得知，该次调整带来了许多问题：
- **引发用户体验的问题**：Go issues 上总是出现以为内存泄露，但其实只是未满足条件，内存没有马上释放的案例。
- **混淆统计信息和监控工具的情况**：在 Grafana 等监控上，发现容器进程内存较高，释放很慢，告警了，很慌。
- **导致与内存使用有关联的个别管理系统集成不良**：例如 Kubernetes HPA ，或者自定义了扩缩容策略这类模式，难以评估。
- **挤压同主机上的其他应用资源**：并不是所有的 Go 程序都一定独立跑在单一主机中，自然就会导致同一台主机上的其他应用受到挤压，这是难以评估的。

从社区反馈来看是问题多多，弊大于利。

官方本想着想着性能更好一些，但是在现实场景中引发了不少的新问题，甚至有提到和 Android 流程管理不兼容的情况。

有种 “捡了芝麻，丢了西瓜” 的感觉。


## Go1.16：峰回路转

既然社区反馈的问题何其多，有没有人提呢？有，超级多。


![](https://imgkr2.cn-bj.ufileos.com/75ee9ea5-a12c-4de1-806f-eeb85f80e61f.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=%252BqN8BOgO5kZXIUhuHy1QyxOOZ30%253D&Expires=1612673513)


多到提出修改回 `MADV_DONTNEED` 的 issues 仅花了 1-2 天的时间就讨论完毕。

很快得出结论且合并 CL 关闭 issues 了。

Go1.16 修改内容如下：

```
func parsedebugvars() {
	// defaults
	debug.cgocheck = 1
	debug.invalidptr = 1
	if GOOS == "linux" {
		debug.madvdontneed = 1
	}
  ...
}
```

直接指定回了 `debug.madvdontneed = 1`，简单粗暴。

## 总结

在本篇文章中，我们针对 Go 语言在 Linux 下的 `madvise` 方法的策略调整进行了历史介绍和说明，同时针对其调整所带来的的副作用及应对措施进行了一一介绍。

本次变更很好的印证了，牵一发动全身的说法。大家在后续应用这块时也要多加注意。

## 参考

- [runtime: default to MADV_DONTNEED on Linux](https://github.com/golang/go/issues/42330)
- [踩坑记： go 服务内存暴涨](https://www.v2ex.com/t/666257?p=1)
- [Go 1.12 关于内存释放的一个改进](https://ms2008.github.io/2019/06/30/golang-madvfree/)

================================================
FILE: content/posts/go/go1.16-mod.md
================================================
---
title: "Go1.16 新特性：Go mod 的后悔药，仅需这一招"
date: 2021-04-05T16:00:13+08:00
images:
tags: 
  - go
---

大家好，我是煎鱼。


前几天 Go 官方正式发布了 1.16 版本。**从这个版本起，环境变量 GO111MODULE 的默认值正式修改为 on**。

![](https://imgkr2.cn-bj.ufileos.com/64ac411e-6361-4b23-b437-78123e16ae5a.png?UCloudPublicKey=TOKEN_8d8b72be-579a-4e83-bfd0-5f6ce1546f13&Signature=NWVlX2CGAsMjMs%252BJH54ZKW1s1fM%253D&Expires=1613623986)

这也意味着 Go modules 将更进一步推进其业务覆盖面，有新老项目共存的小伙伴建议手动将 GO111MODULE 调整为 auto。

**Go1.16 针对 Go modules 放出了一个新特性，能够让维护 Go mod 库的开发者拥有反复吃 “后悔药” 的权力，提醒开发者已发布的 “脏” 版本存在问题**。

这个新特性，对于许多维护和使用公共库（开源、企业等）的小伙伴简直是一个小福音，建议大家都应该要了解这个知识点。

在接下来文章中将进行详细说明和介绍。

## 后悔药：Go mod retract

Go1.16 起可以在 go.mod 文件中使用 `retract` 指令来声明该第三方模块的某些发行版本不能被其他模块使用。

在使用场景上：在发现严重问题或无意发布某些版本后，模块的维护作者可以撤回该版本，支持撤回单个或多个版本。

以前没有办法解决，因此一旦出现就非常麻烦。对应两者的操作如下：

- 维护者：
    - 删除有问题版本的 tag。
    - 重新打一个新版本的 tag。
- 使用者：
    - 发现有问题的版本 tag 丢失，需手动介入。
    - 不知道有问题，由于其他库依赖，因此被动升级而踩坑。

因此在本次 Go1.16 发布后，就拥有了一个**半止损**的新手段了，也可以作为 Go mod 自动更新的大坑的补全办法之一。

## 实战演练

为了方便演示，首先创建一个 Demo 项目（github.com/eddycjy/go-retract-demo），其含有一个基础方法：

```
package go_retract_demo

func HelloWorld() string {
	return "001：脑子进煎鱼了！"
}
```
另外有一个应用工程依赖了该第三方库，代码如下：

```
func main() {
  // import demo "github.com/eddycjy/go-retract-demo"
	s := demo.HelloWorld()
	fmt.Println(s)
}
```

对应的 go.mod 文件如下：

```
module github.com/eddycjy/awesomeProject

go 1.16

require github.com/eddycjy/go-retract-demo v0.0.1
```

### retract 特性演示

但随着时间不断推移，第三方开源库 `eddycjy/go-retract-demo` 即将迭代到 `v0.3.0` 时，发现以往的 `v0.2.0` 是有 BUG 的。

需要紧急的在`v0.3.0` 版本把这个 BUG 修复并提醒出去。此时可以在 `go.mod` 文件中写入 `retract` 指令：

```
module github.com/eddycjy/go-retract-demo

go 1.16

// 因为煎鱼不小心敲错了...
retract v0.2.0
```
指令上面为撤回的原因，后面是具体的版本。如果涉及多版本，可以如下编写：

```
retract (
  v0.1.0
  v0.2.0
)
```

### retract 特性效果

成功发布最新版本 `v0.3.0` 版本并指定 `retract` 后。
所有引用了该库的工程应用，执行 `go list` 就可以看到如下提醒：

```
$ go1.16 list -m -u all
github.com/eddycjy/awesomeProject
github.com/eddycjy/go-retract-demo v0.2.0 (retracted) [v0.3.0]
```

结合该命令，我们日常使用的 IDE（例如：GoLand），其在保存时是会默认执行 `go list` 命令的。**在后续 IDE 支持后，就可以在编码时就快速发现有问题的版本和提示**。

在手动执行 `go get` 时也会出现 `warning` 提示，会把 go.mod 文件上的原因注释显示出来：

```
$ go1.16 get github.com/eddycjy/go-retract-demo@v0.2.0
go: warning: github.com/eddycjy/go-retract-demo@v0.2.0: retracted by module author: 因为煎鱼不小心敲错了...
go: to switch to the latest unretracted version, run:
	go get github.com/eddycjy/go-retract-demo@latest
```
这样就能看到是哪个模块依赖，因为什么原因要求撤回了，非常直观。

## 总结

以往在出问题后每个个体需要跑去问维护者或者看 GitHub Commits，那样总归非常麻烦，很可能一来一回半个钟就没了。

新特性给予了 Go modules 软撤回版本的一个方法，能够把问题更直观的反馈到开发者的手中，再结合日常开发工具的话更是美哉。

但这个特性的完全应用目前也是有一定的阻碍的：

- ~~国内模块代理：需要国内的模块代理也支持 retract ，否则即使你更新了版本也没有提示处理~~。
- IDE：IDE 针对 retract 做一些支持，例如：文字颜色标红、黄等，能够便于开发者更好的识别。

你对 Go modules 的 retract 特性怎么看，欢迎一起留言讨论！

================================================
FILE: content/posts/go/go11.md
================================================
---
title: "Go 语言今年 11 岁，何去何从，现状到底如何？"
date: 2020-11-11T21:21:58+08:00
toc: false
images:
tags: 
  - go
---

不说不知道，一说下一跳。Go 语言已经开源 11 周年了，感觉是一路高歌，Release History （polarisxu 整理）如下：

- 2011 年 3 月 16 日，Go 语言的第一个稳定版本 r56 发布；
- 2012 年 3 月  28 日，Go 语言的第一个正式版本 Go1 发布，并承诺 1.x 的 兼容性；
- 2013 年  5 月 13 日，Go1.1 正式版才发布。
- 2013 年 12 月 1 日，Go1.2 正式发布；
- 2014 年 6 月 18 日，Go1.3 正式发布；
- 2014 年 12 月 10 日，Go1.4 正式发布；
- 2015 年 8 月 19 日，Go1.5 正式发布。该版本实现了自举，即移除了 C 代码，使用 Go 开发 Go 语言；
- 2016 年 2 月 17 日，Go1.6 正式发布；
- 2016 年 8 月 15 日，Go1.7 正式发布；引入 context 包；
- 2017 年 2 月 17 日，Go1.8 正式发布；
- 2017 年 8 月 24 日，Go1.9 正式发布；引入别名；
- 2018 年 2 月 16 日，Go1.10 正式发布；
- 2018 年 8 月 25 日，Go1.11 正式发布。开始强势支持 Go modules；
- 2019 年 3 月 1 日，Go1.12 正式发布；
- 2019 年 9 月 3 日，Go1.13 正式发布；
- 2020 年 2 月 25 日，Go1.14 正式发布；goroutine 支持异步抢占调度；
- 2020 年 8 月 11 日，Go1.15 正式发布；
- 2021 年 2 月，预计 Go1.16 正式发布；将包含新的文件系统接口和支持在构建时的静态文件嵌入，以及链接器的重写，且正式对 Apple Silicon（GOARCH=arm64）Mac 进行支持。

## 目视现在

现在的 Go 语言在国内已经掀起了一浪又一浪的热潮，炒的非常火热。各大平台极客时间、拉勾教育、掘金小册、慕课网等纷纷出现了大量 Go 语言相关的付费专栏/视频。

在现实工作层面，字节跳动、腾讯向 Go 语言侧偏，以及其它各大一二线厂均出现了不少 Go 的岗位，也正预示着当前已经到了一个比较好风口。

在开源项目层面，Kubernetes、Etcd、Prometheus、Docker 等大量的云原生相关组件均以 Go 语言开发，懂一门 Go 语言，排查问题也更方便了。

与企业开发层面，出现了大量其他语言的开发者向 Go 语言转型，在企业的软件开发中出现，新项目用 Go 语言，老项目保留，形成同时维护新老系统，再渐迁的绞杀者模式：

![绞杀者模式](https://image.eddycjy.com/e3789c8026e3e2684f640309f119213a.png)

在面试中比较常见的是 PHP、C++ 语言，就会在企业中形成了 Go+PHP（新+老系统）的局面，又或是 Go 调 CGO 的运行模式。这也得益于 Go 语言的易用性和一定的胶水特性。

在培训机构层面，各大机构都多少曾经向 Go 语言发起过进攻，但目前 Go 语言大多以中高级人才为主，也就是有过其他语言经验的软件开发从业者为主。因此培训机构的市场行情相对较差。

在社会招聘和岗位层面，狭义上来看，与 2018 年我写的 《带你了解一下Golang的市场行情》基本情况仍保持一致：

![image](https://camo.githubusercontent.com/710fc8e25ba15c8b3802d7a33673f798ee0e28abb51ce49743d7348ad8ebb062/68747470733a2f2f692e6c6f6c692e6e65742f323031382f30342f32372f356165323936623735306464382e706e67)

以下为 GoCN 所收集的 “2020 中国Go 开发者调查报告” 的地域分布：

![image](https://static.gocn.vip/photo/2020/16c7f28a-280f-4c30-acd1-81d9b74c3e85.png?x-oss-process=image/resize,w_1920)

目前 Go 语言的大热门地区依然是：北京、上海、深圳，主体集中在一线城市，机会这里最多。

## 看看数据：TIOBE

从 TIOBE 的编程语言排行榜来看，整体上 Go 语言的热门程度并不会特别高（与老牌语言相比），但作为一门编程语言在短短 11 年内已有很不错的表现：

![图来自 GoCN](https://image.eddycjy.com/24b3917d52a3549b598b72932c9d34c9.jpg)

同时业内时常说 Go 语言要干掉 PHP、C++、Java 等，目前来看短期内不现实，官方也没有这方面打算，因为合适的场景选择合适的语言就好了。

TIOBE 提示本月的排名在第 13 名，且最高排名出现在 2020 年 5 月，在第 10 名，近期基本稳定在这个位数附近。至少近年是干不掉老大哥们的，但最近接触的一个运营大佬称其为 “准备霸占未来语言半壁江山” 的语言，你觉得呢？

## 展望未来

Go1 目前一如既往的遵守了 [Go1 兼容性承诺](https://tip.golang.org/doc/go1compat)，这给不少正在使用 Go 语言的企业带来了一注强心针。但给 Go 语言也带来了一些 “麻烦”。那就是存在破坏性变更的变动无法在 Go1 中实现。

因此为了解决一些 ”问题“，也想达到更好的特性目标。2018 年时释出了 Go2 的计划，详细可参见[Go 2, here we come!](https://blog.golang.org/go2-here-we-come)，其中包含了大量的功能特性。

从目前的基本论调和实际情况来看，可兼容实现的，都会在 Go1 实现，例如大家最期待的功能之一 ”泛型“，预计最早会在 Go1.17 会释出，样例：

```
// Print prints the elements of any slice.
// Print has a type parameter T and has a single (non-type)
// parameter s which is a slice of that type parameter.
func Print[T any](s []T) {
	// same as above
}
```

其在 6 月下旬发布了最新的设计草稿，若对泛型有更进一步需求可关注 [design/go2draft-type-parameters](https://github.com/golang/proposal/blob/master/design/go2draft-type-parameters.md)，而一些不兼容的修改，若确切评估后无法直接实现的，将会到 Go2 的 计划中去：

![image](https://image.eddycjy.com/eb173beda6d6f989c65d28b0129edd1c.jpg)

并且相信 Go2 发布时，肯定也不是 `go run xxx` 了，估计会变更命令集，以示区分。

## 总结

11 岁，Go 语言目前在国内已经火起来了，但现阶段的 ”成功“ 并不代表后续一定持续强劲，背后离不开所有开发者在社区开源的努力。我们一起思考如下问题：

- 你最喜欢 Go 语言哪些方面？

- 你认为 Go 语言目前还有哪些问题呢？ 期望他解决哪一块内容？

- 如果 Go 语言想继续占领更多的语言市场，需要在什么领域发力？

以更具现化的 TLOBE Index for Go 趋势图来看：

![image](https://image.eddycjy.com/a8f3d88382c1473df54458a5aef80eaa.jpg)

你认为 2020 年后 Go 语言的走向会是怎么样，现在适合 “抄底” 吗？


================================================
FILE: content/posts/go/go16-preview.md
================================================
---
title: "为什么 Go 的泛型一拖再拖？"
date: 2020-11-12T23:47:16+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。前段时间 Go 语言的泛型讨论频频出现在各微信群，且又冲上了国内外各大文章的 “头条”：

![来自 p 神公众号的截图](https://image.eddycjy.com/c9c48e9479c7036f7d5a33b6ab49e855.jpg)

信息汇总来看，Go 泛型这几年会出，但大体来讲现在 Go 泛型又又又推迟了，好家伙。我最早了解到时是考虑 Go1.16 释出，后面又推到了 Go1.17，接着现在又延期到了 Go1.18 了（2021 年底）。

看到了信息的表象后，再想想为什么泛型 “这件事情” 突然醒目起来了，其原因之一是由官方 [Go，11 岁](https://blog.golang.org/11years) 的博文所引爆的。

同时近日举办的 GopherCon2020 大会，Robert Griesemer 分享的 Typing [Generic] Go。更正式的让 Go 泛型更面向了大众，也侧面的说明官方认为其已经到达了一个新的阶段了，进入最终实现阶段。

事不宜迟，既然官方都已经摩拳擦掌了，我们的学习之路也得跟上，因此本文将会介绍 Go 泛型现在的情况，并通过在介绍过程中不断思考最后得出一个为什么。

## 什么是泛型

泛型程序设计（generic programming）是程序设计语言的一种风格或范式。泛型允许程序员在强类型语言中编写代码时，使用一些以后才确定的类型，其在真正实例化时才会为这些参数指确定类型。另外各语言和其编译器、运行环境对泛型的支持均不一样，因此需要针对来辩证。

简单来讲，泛型就是参数化多态。其可根据实参类型生成不同的版本，支持任意数量的调用：

```
func F(a, b T) T{ return a+b }

// T 为 int
F(1, 2)

// T 为 string
F("1", "2")
```

在编译时期编译器便确定其 T 的入参类型。这也是 Go 泛型实现的要求之一 “编译时类型安全”。

## 为什么需要泛型

这时候可能会有人说，没有泛型也可以啊...感觉写业务代码没什么影响，与其搞泛型不如搞好 errors（具体新消息可参见：重磅：Go errors 将不会有任何进一步的改进计划）。

但泛型是有其所需的场景，最常见的是像基础库在处理获取配置中心数据时，就要处理类型，时常遇到下述场景：

![image](https://image.eddycjy.com/4d630c956a58bd4b88a4a6e0cddbb845.gif)

如果使用接口（interface）类型来做，也得 `switch.(type)` 枚举出所有的基础类型。这显然并不合理，也没法做太复杂的逻辑，而且所支持的类型还泄露。

另外同时单从语言层面来讲，泛型支持是一个必然事件了，因为泛型的存在对解决特定领域的问题存在一定的意义。

## 接口和泛型有什么区别

在上面我们有提到接口（interface）类型，这时候就出现了泛型的第二个经典问题。那就是 “接口和泛型有什么区别？”，为什么不用接口来实现 “泛型”：

```
type T interface { ... }
func F(a, b T) T { return a+b }
```

也像这么一回事，但在这里存在一个致命的缺陷。那就是接口的入参和出参均可以在运行时表现为不同的类型：

```
F("煎鱼", 233)
```

要做好，还得依靠内部去对参数进行断言，否则作为 string 类型的煎鱼又如何和 int 类型的 233 相加呢，那是必然报错的。

而反过来看真 “泛型” 的实际使用，编译器会保证泛型函数的入参和出参必须为同一类型，有强制性的检验：

```
// 报错：type checking failed for main
F("煎鱼", 233)

// 必须为同一类型，才能正常运行
F(666, 233)
```

两者存在本质上的区别，泛型会更安全，能够保证编译早期就发现错误，而不是等到运行时（并且可能会存在隐性的 BUG）。

总体来讲，泛型相较接口有如下优点：

- 更安全：编译早期就能发现错误。

- 性能好：静态类型。

## 过去：为什么那么久都没有泛型

前几段在社区的微信群看到一位小伙伴吐槽 “Go 语言居然没有泛型？”，变相来看，可能其会认为 ”Go 都已经 11 岁了，2020 年了居然还没有泛型？”。

这显然是不对的，因为泛型本质上并不是绝对的必需品，更不是 Go 语言的早期目标，因此在过往的发展阶段没有过多重视这一点，而是把精力放在了其他 feature 上。

另外 Go 语言在以往其实进行过大量的泛型 proposal 试验，基本时间线（via @changkun）如下：

|  简述   | 时间  | 作者 |
|  ----  | ----  | --- |
| [Type Functions]  | 2010年 | Ian Lance Taylor |
| Generalized Types  | 2011年 | Ian Lance Taylor |
| Generalized Types v2  | 2013年 | Ian Lance Taylor |
| Type Parameters  | 2013年 | Ian Lance Taylor |
| go:generate  | 2014年 | Rob Pike |
| First Class Types  | 2015年 | Bryan C.Mills |
| Contracts  | 2018年 | Ian Lance Taylor, Robert Griesemer |
| Contracts  | 2019年 | Ian Lance Taylor, Robert Griesemer  |
| Redundancy in Contracts(2019)'s Design  | 2019年 | Ian Lance Taylor, Robert Griesemer |
| Constrained Type Parameters(2020, v1)  | 2020年 | Ian Lance Taylor, Robert Griesemer |
| Constrained Type Parameters(2020, v2)  | 2020年 | Ian Lance Taylor, Robert Griesemer |
| Constrained Type Parameters(2020, v3)  | 2020年 | Ian Lance Taylor, Robert Griesemer |

虽然偶有中断，但仔细一看，2010 年就尝试过，现在 2020 年了，也是很励志了，显然官方也是在寻路和尝试的过程中，但一直没有找到相较好的方案，争端过多了。

## 现在：Go 泛型

泛型尝鲜的方式有两种方式。线上 Ian Lance Taylor 提供了一个在线编译的 [go2go](https://go2goplay.golang.org/)：

![image](https://image.eddycjy.com/0609310f0a775b57fe017f56c1e50195.jpg)

另外一种是线下，也就在本地安装 Go 的特定分支版本：

```
$ git clone https://github.com/golang/go
$ git checkout dev.go2go
$ cd src && ./all.bash
```

不过这种本地安装的方法会耗时比较久，初步尝试的话建议使用 go2go 就可以了。而在尝鲜时，可以看到在代码块中声明了一个 `Print` 方法，其函数签名主体分为三部分：

![image](https://image.eddycjy.com/5fc715bb226563645dfc6bb4da210c84.jpg)

咋一看，变量 T 的这个关键字 `any` 是什么？早期泛型你可能有听说合约（Contract），难道这就是合约。其实严格意义上来讲并不是，因为为了更一步简化语法，合约在 2020.06.07 已经正式移除。

其已改头换面，现在只需要写参数化的 interface。而上述的 `any` 关键字是一个预定义的类型约束，声明后将允许任何类型用作类型实参，并且允许函数使用用于任何类型的操作。

从语法分析的角度来讲，`Print` 方法一共包含了如下属性（从左到右）：

- type list：声明了入参的类型列表为一个 `T` 变量，其可以传任意类型的参数。

- parameter list：声明了入参的参数列表为 `T` 变量的切片，且形参为 `s`。

- return type list：声明了函数的返回参数列表。

上述函数签名便是一个 Go 泛型的基本样子，由于本文并不是 CRUD 泛型，便不展开案例，若大家有兴趣可以详细阅读提案：[Type Parameters - Draft Design](https://github.com/golang/proposal/blob/master/design/go2draft-type-parameters.md)。

## 泛型的战争

### 为什么不用尖括号

在社区中很多同学在讨论的一个问题，那就是 “为什么 Go 泛型不像 C++ 和 Java 那样使用尖括号？，也出现了 “Go 一直标榜业界工程实践类的榜样，为什么就是不用尖括号” 的言论？

思考问题我们不只看表面，官方说不行，那么我们可以倒推来看，看看 Go 语言就用尖括号：

```
func print<type T>(list []T) {

print<int>(numbers)
print<string>(strings)
print<float64>(floats)
```

普通的函数声明看上去似乎结构清晰，没有什么大问题的。接着往下看：

```
a := w < x
b := y > (z)
```

我们继续把代码演进一下，简洁一点：

```
a, b := w < x, y > (z)
```

这时候就犯难了，不仅编译器难以解析，人也很难判别，到底指的是：

```
a := w < x
b := y > (z)
```

又或是：

```
a, b := w<x, y>(z)
```

从上述代码来看，使用尖括号难以分别，因为没有类型信息，就无法确定赋值的右侧是一对表达式 `w < x和y > (z)`，还是返回两个结果值 `w<x, y>(z)` 的泛型函数实例化和调用，其存在歧义。

要解决还要引入新的约束，会破坏 Go1 的兼容性承诺，这显然是不合理的。

### 为什么不用括号

其实最早 Go 泛型的版本是使用了括号的模式，虽然能用，但是用括号会引入新的解析歧义。例如：

```
var f func(x(T))
```

从语法上来讲，你无法识别他是未命名参数的 `x(T)` 函数，还是类型名为参数的 `(T)` 函数。同时 Go 语言还存在强制类型转换这一语法，假设代码是 `[]T(v1)` 和 `[]T(v2){}` ，那么你在开括号处，就无法得知其是否代表类型转换。

更甚至在函数的完整声明上，我们都会感到困惑：

```
func F(T any)(v T)(r1, r2 T)
```

函数入参、泛型、返回值声明均都是括号，造成了语义不清，这显然也是不合理的。

### 为什么不用书名号（«»）

想的美，并不想使用非 ASCII，未来更没打算支持。

## 总结

在本文中我们从多个维度介绍了 Go 泛型的相关内容，既了解到了上段时间 Go 泛型再度火爆的信息来源是什么。也知道了 Go 泛型是什么，与接口的区别。

同时我们还针对业界常见的一些疑问，例如接口和泛型的区别，泛型的历史，泛型的尖括号/括号/书名号之争进行了解释和说明。

最后我们回答一下最开始的疑问，”为什么 Go 的泛型一拖再拖“，主要如下：

- Go 语言的早期目标（工作重点）并不是泛型。

- Go 语言在 2010-2020 年都有间断在做 Go 泛型的 proposal，但总是 ”失败“，在不断地吸收经验。

- Go 语言社区的意见反馈是真的多，单用什么符号表示泛型，不想要泛型都争论不休。

- Go 语言的泛型现在还不成熟，很多​细节其实并没有支持好。

很显然，在保证 Go1 向后兼容性的同时，Go 官方也不想直接妥协出一个随便的方案，因此总是不断地在改进。随着 Go 语言的不断应用，泛型也和 errors 一样被推上风头浪尖。

## 到底拖到什么时候

那 Go 泛型到底什么时候出呢？

前段时间也向欧神（@changkun）了解到在 GopherCon 2020 Go Team AMA，russ cox 有聊到相关问题，表示在明年年底要能有生产环境的试用版上线，这是一个管理目标。

但具体真正的时间线肯定是要看泛型的实现者：robert 和 keith，可以多多关注他们，就能拿到一手信息，且可以确定的是 Go 泛型明年二月之前是不会有生产可用的试用版。

**灵魂拷问：你对 Go 语言的泛型又有什么想法和意见呢，一起留言讨论吧。**

## 推荐阅读

- [欧神：第 80 期 2020-03-18 带你提前玩 Go 2 新特性：泛型](https://talkgo.org/t/topic/99)
- [提案：Type Parameters - Draft Design](https://github.com/golang/proposal/blob/master/design/go2draft-type-parameters.md)


================================================
FILE: content/posts/go/go2-errors.md
================================================
---
title: "先睹为快，Go2 Error 的挣扎之路"
date: 2020-12-03T20:56:47+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

自从 Go 语言在国内火热以来，除去泛型，其次最具槽点的就是 Go 对错误的处理方式，一句经典的 `if err != nil`  暗号就能认出你是一个 Go 语言爱好者。

![image](https://image.eddycjy.com/381fcb5e85923479666f5be14de3782c.jpeg)

自然，大家对 Go error 的关注度更是高涨，Go team 也是，因此在 [Go 2 Draft Designs](https://github.com/golang/proposal/blob/master/design/go2draft.md) 中正式提到了 error handling（错误处理）的相关草案，希望能够在未来正式的解决这个问题。

在今天这篇文章中，我们将一同跟踪 Go2 error，看看他是怎么 “挣扎” 的，能不能破局？

## 为什么要吐槽 Go1 

要吐槽 Go1 error，就得先知道为什么大家到底是在喷 Error 哪里处理的不好。在 Go 语言中，error 其实本质上只是个 Error 的 `interface`：

```
type error interface {
    Error() string
}
```

实际的应用场景如下：

```
func main() {
	x, err := foo()
	if err != nil {
		 // handle error
	}
}
```

单纯的看这个例子似乎没什么问题，但工程大了后呢？显然 `if err != nil` 的逻辑是会堆积在工程代码中，Go 代码里的 `if err != nil` 甚至会达到工程代码量的 30% 以上：

```
func main() {
	x, err := foo()
	if err != nil {
		 // handle error
	}
	y, err := foo()
	if err != nil {
		 // handle error
	}
	z, err := foo()
	if err != nil {
		 // handle error
	}
	s, err := foo()
	if err != nil {
		 // handle error
	}
}
```

暴力的对比一下，就发现四行函数调用，十二行错误，还要苦练且精通 IDE 的快速折叠功能，还是比较麻烦的。

另外既然是错误处理，那肯定不单单是一个 `return err` 了。在工程实践中，项目代码都是层层嵌套的，如果直接写成：

```
if err != nil {
	return err
}
```

在实际工程中肯定是不行。你怎么知道具体是哪里抛出来的错误信息，实际出错时只能瞎猜。大家又想出了 PlanB，那就是加各种描述信息：

```
if err != nil {
	logger.Errorf("煎鱼报错 err：%v", err)
	return err
}
```
虽然看上去人模人样的，在实际出错时，也会遇到新的问题，因为你要去查这个错误是从哪里抛出来的，单纯几句错误描述是难以定位的。这时候就会发展成**到处打错误日志**：

```
func main() {
	err := bar()
	if err != nil {
		logger.Errorf("bar err：%v", err)
	}
	...
}

func bar() error {
	_, err := foo()
	if err != nil {
		logger.Errorf("foo err：%v", err)
		return err
	}

	return nil
}

func foo() ([]byte, error) {
	s, err := json.Marshal("hello world.")
	if err != nil {
		logger.Errorf("json.Marshal err：%v", err)
		return nil, err
	}

	return s, nil
}
```

虽然到处打了日志，就会变成错误日志非常多，一旦出问题，人肉可能短时间内识别不出来。且最常见的就是到 IDE 上 `ctrl + f` 搜索是在哪出错，同时在我们常常会自定义一些错误类型，而在 Go 则需要各种判断和处理：

```
if err := dec.Decode(&val); err != nil {
    if serr, ok := err.(*json.SyntaxError); ok {
       ...
    }
    return err
}
```

首先你得判断不等于 `nil`，还得对自定义的错误类型进行断言，整体来讲比较繁琐。

汇总来讲，Go1 错误处理的问题至少有：

- 在工程实践中，`if err != nil` 写的烦，代码中一大堆错误处理的判断，占了相当的比例，不够优雅。

- 在排查问题时，Go 的 `err` 并没有其他堆栈信息，只能自己增加描述信息，层层叠加，打一大堆日志，排查很麻烦。

- 在验证和测试错误时，要自定义错误（各种判断和断言）或者被迫用字符串校验。

## Go1.13 的挽尊

在 2019 年 09 月，Go1.13 正式发布。其中两个比较大的两个关注点分别是包依赖管理 Go modules 的转正，以及错误处理 errors 标准库的改进：

![image](https://image.eddycjy.com/51485fae58cbf9bd92aa19686caf5a27.jpg)

在本次改进中，errors 标准库引入了 Wrapping Error 的概念，并增加了 Is/As/Unwarp 三个方法，用于对所返回的错误进行二次处理和识别。同时也是将 Go2 error 预规划中没有破坏 Go1 兼容性的相关功能提前实现了。

简单来讲，Go1.13 后 Go 的 error 就可以嵌套了，并提供了三个配套的方法。例子：

```
func main() {
	e := errors.New("脑子进煎鱼了")
	w := fmt.Errorf("快抓住：%w", e)
	fmt.Println(w)
	fmt.Println(errors.Unwrap(w))
}
```

输出结果：

```
$ go run main.go
快抓住：脑子进煎鱼了
脑子进煎鱼了
```

在上述代码中，变量 `w` 就是一个嵌套一层的 error。最外层是 “快抓住：”，此处调用 `%w` 意味着 Wrapping Error 的嵌套生成。因此最终输出了 “快抓住：脑子进煎鱼了”。

需要注意的是，Go 并没有提供 `Warp` 方法，而是直接扩展了 `fmt.Errorf` 方法。而下方的输出由于直接调用了 `errors.Unwarp` 方法，因此将 “取” 出一层嵌套，最终直接输出 “脑子进煎鱼了”。

对 Wrapping Error 有了基本理解后，我们简单介绍一下三个配套方法：

```
func Is(err, target error) bool
func As(err error, target interface{}) bool
func Unwrap(err error) error
```

### errors.Is

方法签名：

```
func Is(err, target error) bool
```

方法例子：

```
func main() {
	if _, err := os.Open("non-existing"); err != nil {
		if errors.Is(err, os.ErrNotExist) {
			fmt.Println("file does not exist")
		} else {
			fmt.Println(err)
		}
	}

}
```

`errors.Is` 方法的作用是判断所传入的 err 和 target 是否同一类型，如果是则返回 true。

### errors.As

方法签名：

```
func As(err error, target interface{}) bool
```

方法例子：

```
func main() {
	if _, err := os.Open("non-existing"); err != nil {
		var pathError *os.PathError
		if errors.As(err, &pathError) {
			fmt.Println("Failed at path:", pathError.Path)
		} else {
			fmt.Println(err)
		}
	}

}
```

`errors.As` 方法的作用是从 err 错误链中识别和 target 相同的类型，如果可以赋值，则返回 true。

### errors.Unwarp

方法签名：

```
func Unwrap(err error) error
```

方法例子：

```
func main() {
	e := errors.New("脑子进煎鱼了")
	w := fmt.Errorf("快抓住：%w", e)
	fmt.Println(w)
	fmt.Println(errors.Unwrap(w))
}
```

该方法的作用是将嵌套的 error 解析出来，若存在多级嵌套则需要调用多次 Unwarp 方法。

## 民间自救 pkg/errors

Go1 的 error 处理固然存在许多问题，因此在 Go1.13 前，早已有 “民间” 发现没有上下文调试信息在实际工程应用中存在严重的体感问题。因此 `github.com/pkg/errors` 在 2016 年诞生了，目前该库也已经受到了极大的关注。

官方例子如下：

```
type stackTracer interface {
    StackTrace() errors.StackTrace
}

err, ok := errors.Cause(fn()).(stackTracer)
if !ok {
    panic("oops, err does not implement stackTracer")
}

st := err.StackTrace()
fmt.Printf("%+v", st[0:2]) // top two frames

// Example output:
// github.com/pkg/errors_test.fn
//	/home/dfc/src/github.com/pkg/errors/example_test.go:47
// github.com/pkg/errors_test.Example_stackTrace
//	/home/dfc/src/github.com/pkg/errors/example_test.go:127
```

简单来讲，就是对 Go1 error 的上下文处理进行了优化和处理，例如类型断言、调用堆栈等。若有兴趣的小伙伴可以自行到 `github.com/pkg/errors` 进行学习。

另外你可能会发现 Go1.13 新增的 Wrapping Error 体系与 `pkg/errors` 有些相像。你并没有体会错，Go team 接纳了相关的意见，对 Go1 进行了调整，但调用堆栈这块因综合原因暂时没有纳入。

## Go2 error 要解决什么问题

在前面我们聊了 Go1 error 的许多问题，以及 Go1.13 和 `pkg/errors` 的自救和融合。你可能会疑惑，那...Go2 error 还有出场的机会吗？即使 Go1 做了这些事情，Go1 error 还有问题吗？

并没有解决，`if err != nil` 依旧一把梭，目前社区声音依然认为 Go 语言的错误处理要改进。

## Go2 error proposal

在 2018 年 8 月，官方正式公布了 [Go 2 Draft Designs](https://go.googlesource.com/proposal/+/master/design/go2draft.md)，其中包含泛型和错误处理机制改进的初步草案：

![image](https://image.eddycjy.com/48b07b14442b1832c09eb6e2bc35fb6b.jpg)

注：Go1.13 正式将一些不破坏 Go1 兼容性的 Error 特性加入到了 main branch，也就是前面提到的 Wrapping Error。

### 错误处理（Error Handling）

第一个要解决的问题就是大量 `if err != nil` 的问题，针对此提出了 [Go2 error handling](https://github.com/golang/proposal/blob/master/design/go2draft-error-handling-overview.md) 的草案设计。

简单例子：

```
if err != nil {
	return err
}
```

优化后的方案如下：

```
func CopyFile(src, dst string) error {
	handle err {
		return fmt.Errorf("copy %s %s: %v", src, dst, err)
	}

	r := check os.Open(src)
	defer r.Close()

	w := check os.Create(dst)
	handle err {
		w.Close()
		os.Remove(dst) // (only if a check fails)
	}

	check io.Copy(w, r)
	check w.Close()
	return nil
}
```

主函数：

```
func main() {
	handle err {
		log.Fatal(err)
	}

	hex := check ioutil.ReadAll(os.Stdin)
	data := check parseHexdump(string(hex))
	os.Stdout.Write(data)
}
```

该提案引入了两种新的语法形式，首先是 `check` 关键字，其可以选中一个表达式 `check f(x, y, z)` 或 `check err`，其将会标识这是一个显式的错误检查。

其次引入了 `handle` 关键字，用于定义错误处理程序流转，逐级上抛，依此类推，直到处理程序执行 `return` 语句，才正式结束。

### 错误值打印（Error Printing）

第二个要解决的问题是错误值（Error Values）、错误检查（Error Inspection）的问题，其引申出错误值打印（Error Printing）的问题，也可以认为是错误格式化的不便利。

官方针对此提出了提出了 [Error Values](https://github.com/golang/proposal/blob/master/design/go2draft-error-values-overview.md) 和 [Error Printing](https://github.com/golang/proposal/blob/master/design/go2draft-error-printing.md) 的草案设计。

简单例子如下：

```
if err != nil {
	return fmt.Errorf("write users database: %v", err)
}
```

优化后的方案如下：

```
package errors

type Wrapper interface {
	Unwrap() error
}

func Is(err, target error) bool
func As(type E)(err error) (e E, ok bool)
```

该提案增加了错误链的 Wrapping Error 概念，并同时增加 `errors.Is` 和 `errors.As` 的方法，与前面说到的 Go1.13 的改进一致，不再赘述。

需要留意的是，Go1.13 并没有实现 `%+v` 输出调用堆栈的需求，因为此举会破坏 Go1 兼容性和产生一些性能问题，大概会在 Go2 加入。

## try-catch 不香吗

社区中另外一股声音就是直指 Go 语言反人类不用 `try-catch` 的机制，在社区内也产生了大量的探讨，具体可以看看相关的提案 [Proposal: A built-in Go error check function, "try"](https://github.com/golang/go/issues/32437)。

目前该提案已被拒绝，具体可参见 [go/issues/32437#issuecomment-512035919](https://github.com/golang/go/issues/32437#issuecomment-512035919) 和 [Why does Go not have exceptions](https://golang.org/doc/faq#exceptions)。

## 总结

在这篇文章中，我们介绍了目前 Go1 Error 的现状，概括了大家对 Go 语言错误处理的常见问题和意见。同时还介绍了在这几年间，Go team 针对 Go2、Go1.13 Error 的持续优化和探索。

如果是你，你会怎么去优化目前 Go 语言的错误处理机制呢，现在 Go2 error proposal 你又是否认可？

## 参考

- [Golang error 的突围](https://qcrao.com/2019/09/18/golang-error-break-through)

- [为什么 Go 语言的 Error Handling 是一个败笔](https://www.zhihu.com/question/330263279)

- [Go语言(golang)新发布的1.13中的Error Wrapping深度分析](https://www.flysnow.org/2019/09/06/go1.13-error-wrapping.html)

================================================
FILE: content/posts/go/gophercon2020-errors.md
================================================
---
title: "重磅：Go errors 将不会有任何进一步的改进计划"
date: 2020-11-14T16:48:33+08:00
images:
tags: 
  - go
---

今天在 Gophercon2020 上，**Go 1.13 错误提案的作者事后提及他对目前错误格式化的缺失表示遗憾，而且在未来很长的好几年内都不会有任何进一步改进计划**。

对此他本人给出的原因之一是：对于错误处理这一领域特定的问题，在他的能力范围内实在是无法给出一个令所有人都满意的方案。

尽管如此，在他演讲的最后，还是给出了一些关于错误嵌套的建议，即实现 `fmt.Formatter`，图中给出了一个简单的例子，大家可以参考如下代码：

```
type DetailError struct {
	msg, detail string
	err         error
}

func (e *DetailError) Unwrap() error { return e.err }

func (e *DetailError) Error() string {
	if e.err == nil {
		return e.msg
	}
	return e.msg + ": " + e.err.Error()
}

func (e *DetailError) Format(s fmt.State, c rune) {
	if s.Flag('#') && c == 'v' {
		type nomethod DetailError
		fmt.Fprintf(s, "%#v", (*nomethod)(e))
		return
	}
	if !s.Flag('+') || c != 'v' {
		fmt.Fprintf(s, spec(s, c), e.Error())
		return
	}
	fmt.Fprintln(s, e.msg)
	if e.detail != "" {
		io.WriteString(s, "\t")
		fmt.Fprintln(s, e.detail)
	}
	if e.err != nil {
		if ferr, ok := e.err.(fmt.Formatter); ok {
			ferr.Format(s, c)
		} else {
			fmt.Fprintf(s, spec(s, c), e.err)
			io.WriteString(s, "\n")
		}
	}
}

func spec(s fmt.State, c rune) string {
	buf := []byte{'%'}
	for _, f := range []int{'+', '-', '#', ' ', '0'} {
		if s.Flag(f) {
			buf = append(buf, byte(f))
		}
	}
	if w, ok := s.Width(); ok {
		buf = strconv.AppendInt(buf, int64(w), 10)
	}
	if p, ok := s.Precision(); ok {
		buf = append(buf, '.')
		buf = strconv.AppendInt(buf, int64(p), 10)
	}
	buf = append(buf, byte(c))
	return string(buf)
}
```

此处的内容来源于欧神（@changkun）在知识星球里的线上分享，作为 Go 夜读 SIG 成员的一员，借此也安利下咱们《Go 夜读》的星球，欢迎大家一起来学习和分享：

![image](https://image.eddycjy.com/f474866fbaed634f83fa2e3228cfbec6.jpeg)

## 讨论

Go 语言的错误处理机制一直饱受争议，前段时间在 issues 中还长期争吵过一段时间，因此还是维持了目前 `if err != nil` 的方式，也没有什么大改动。

我们再想想，像其他语言的 `try catch` 是一定好吗？毕竟 `try catch` 的方式也有很多人不看好。抛个砖，**如果是你，你会想怎么设计 Go 语言的错误机制？或者说你觉得怎么的处理才算好**？

================================================
FILE: content/posts/go/goroutine-27.md
================================================
---
title: "会诱发 Goroutine 挂起的 27 个原因"
date: 2021-12-31T12:55:06+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

上个月面向读者的提问，我们针对 goroutine 泄露中都会看到的大头 runtime.gopark 函数进行了学习和了解，输出了 《[Goroutine 一泄露就看到他，这是个什么？](https://mp.weixin.qq.com/s/x6Kzn7VA1wUz7g8txcBX7A)》。

有小伙伴提到，虽然我们知道了 runtime.gopark 函数的缘起和内在，但其实没有提到 **runtime.gopark 的诱发因素，这是我们日常编码中需要关注的**。

今天这篇文章就和大家一起围观 gopark 的 27 个诱发场景。为了方便阅读，我们会根据分类进行说明。

### 第一部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonZero  |   无  |
|   waitReasonGCAssistMarking  |   GC assist marking  |
|   waitReasonIOWait  |   IO wait |

- waitReasonZero：无正式解释，从使用情况来看。主要在 sleep 和 lock 的 2 个场景中使用。
- waitReasonGCAssistMarking：GC 辅助标记阶段会使得阻塞等待。
- waitReasonIOWait：IO 阻塞等待时，例如：网络请求等。

### 第二部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonChanReceiveNilChan  |   chan receive (nil chan)  |
|   waitReasonChanSendNilChan  |   chan send (nil chan)  |

- waitReasonChanReceiveNilChan：对未初始化的 channel 进行读操作。
- waitReasonChanSendNilChan：对未初始化的 channel 进行写操作。

### 第三部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonDumpingHeap  |  dumping heap |
|   waitReasonGarbageCollection  |   garbage collection  |
|   waitReasonGarbageCollectionScan  |   garbage collection scan  |

- waitReasonDumpingHeap：对 Go Heap 堆 dump 时，这个的使用场景仅在 runtime.debug 时，也就是常见的 pprof 这一类采集时阻塞。
- waitReasonGarbageCollection：在垃圾回收时，主要场景是 GC 标记终止（GC Mark Termination）阶段时触发。
- waitReasonGarbageCollectionScan：在垃圾回收扫描时，主要场景是 GC 标记（GC Mark）扫描 Root 阶段时触发。

### 第四部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonPanicWait  |  panicwait |
|   waitReasonSelect  |   select  |
|   waitReasonSelectNoCases  |   select (no cases)  |

- waitReasonPanicWait：在 main goroutine 发生 panic 时，会触发。
- waitReasonSelect：在调用关键字 select 时会触发。
- waitReasonSelectNoCases：在调用关键字 select 时，若一个 case 都没有，会直接触发。

### 第五部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonGCAssistWait  |  GC assist wait |
|   waitReasonGCSweepWait  |   GC sweep wait  |
|   waitReasonGCScavengeWait  |   GC scavenge wait  |

- waitReasonGCAssistWait：GC 辅助标记阶段中的结束行为，会触发。
- waitReasonGCSweepWait：GC 清扫阶段中的结束行为，会触发。
- waitReasonGCScavengeWait：GC scavenge 阶段的结束行为，会触发。GC Scavenge 主要是新空间的垃圾回收，是一种经常运行、快速的 GC，负责从新空间中清理较小的对象。

### 第六部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonChanReceive  |  chan receive |
|   waitReasonChanSend  |   chan send  |
|   waitReasonFinalizerWait  |   finalizer wait  |

- waitReasonChanReceive：在 channel 进行读操作，会触发。
- waitReasonChanSend：在 channel 进行写操作，会触发。
- waitReasonFinalizerWait：在 finalizer 结束的阶段，会触发。在 Go 程序中，可以通过调用 `runtime.SetFinalizer` 函数来为一个对象设置一个终结者函数。这个行为对应着结束阶段造成的回收。

### 第七部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonForceGCIdle  |  force gc (idle) |
|   waitReasonSemacquire  |   semacquire  |
|   waitReasonSleep  |   sleep  |

- waitReasonForceGCIdle：强制 GC（空闲时间）结束时，会触发。
- waitReasonSemacquire：信号量处理结束时，会触发。
- waitReasonSleep：经典的 sleep 行为，会触发。

### 第八部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonSyncCondWait  |  sync.Cond.Wait |
|   waitReasonTimerGoroutineIdle  |   timer goroutine (idle)  |
|   waitReasonTraceReaderBlocked  |   trace reader (blocked)  |

- waitReasonSyncCondWait：结合 `sync.Cond` 用法能知道，是在调用 `sync.Wait` 方法时所触发。
- waitReasonTimerGoroutineIdle：与 Timer 相关，在没有定时器需要执行任务时，会触发。
- waitReasonTraceReaderBlocked：与 Trace 相关，ReadTrace会返回二进制跟踪数据，将会阻塞直到数据可用。

### 第九部分

|  标识   |  含义   |
| --- | --- |
|   waitReasonWaitForGCCycle  |  wait for GC cycle |
|   waitReasonGCWorkerIdle  |   GC worker (idle)  |
|   waitReasonPreempted  |   preempted  |
|   waitReasonDebugCall  |   debug call  |

- waitReasonWaitForGCCycle：等待 GC 周期，会休眠造成阻塞。
- waitReasonGCWorkerIdle：GC Worker 空闲时，会休眠造成阻塞。
- waitReasonPreempted：发生循环调用抢占时，会会休眠等待调度。
- waitReasonDebugCall：调用 GODEBUG 时，会触发。

## 总结

今天这篇文章是对开头 runtime.gopark 函数的详解文章的一个补充，我们能够对此了解到其诱发的因素。

主要场景为：
1. 通道（Channel）。
2. 垃圾回收（GC）。
3. 休眠（Sleep）。
4. 锁等待（Lock）。
5. 抢占（Preempted）。
6. IO 阻塞（IO Wait）
7. 其他，例如：panic、finalizer、select 等。

我们可以根据这些特性，去拆解可能会造成阻塞的原因。其实也就没必要记了，他们会导致阻塞肯定是由于存在影响控制流的因素，才会导致 gopark 的调用。

活学活用：）

================================================
FILE: content/posts/go/goroutine-errors.md
================================================
---
title: "多 Goroutine 如何优雅处理错误？"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在 Go 语言中，goroutine 的使用是非常频繁的，因此在日常编码的时候我们会遇到一个问题，那就是 goroutine 里面的错误处理，怎么做比较好？

![](https://files.mdnice.com/user/3610/72758b15-f9b7-4437-ba17-b37a36f285ae.png)


这是来自我读者群的问题。作为一个宠粉煎鱼，我默默记下了这个技术话题。今天煎鱼就大家来看看多 goroutine 的错误处理机制也有哪些！

一般来讲，我们的业务代码会是：

```golang
func main() {
	var wg sync.WaitGroup
	wg.Add(2)
	go func() {
		log.Println("脑子进煎鱼了")
		wg.Done()
	}()
	go func() {
		log.Println("煎鱼想报错...")
		wg.Done()
	}()

	time.Sleep(time.Second)
}
```

在上述代码中，我们运行了多个 goroutine。但我想抛出 error 的错误信息出来，似乎没什么好办法...

## 通过错误日志记录

为此，业务代码中常见的第一种方法：通过把错误记录写入日志文件中，再结合相关的 logtail 进行采集和梳理。

但这又会引入新的问题，那就是调用错误日志的方法写的到处都是。代码结构也比较乱，不直观。

最重要的是无法针对 error 做特定的逻辑处理和流转。

## 利用 channel 传输

这时候大家可能会想到 Go 的经典哲学：**不要通过共享内存来通信，而是通过通信来实现内存共享**（Do not communicate by sharing memory; instead, share memory by communicating）。

第二种的方法：利用 channel 来传输多个 goroutine 中的 errors：

```golang
func main() {
	gerrors := make(chan error)
	wgDone := make(chan bool)

	var wg sync.WaitGroup
	wg.Add(2)

	go func() {
		wg.Done()
	}()
	go func() {
		err := returnError()
		if err != nil {
			gerrors <- err
		}
		wg.Done()
	}()

	go func() {
		wg.Wait()
		close(wgDone)
	}()

	select {
	case <-wgDone:
		break
	case err := <-gerrors:
		close(gerrors)
		fmt.Println(err)
	}

	time.Sleep(time.Second)
}

func returnError() error {
	return errors.New("煎鱼报错了...")
}
```

输出结果：

```golang
煎鱼报错了...
```

虽然使用 channel 后已经方便了不少。但自己编写 channel 总是需要关心一些非业务向的逻辑。

## 借助 sync/errgroup

因此第三种方法，就是使用官方提供的 `sync/errgroup` 标准库：

```golang
type Group
    func WithContext(ctx context.Context) (*Group, context.Context)
    func (g *Group) Go(f func() error)
    func (g *Group) Wait() error
```

- Go：启动一个协程，在新的 goroutine 中调用给定的函数。
- Wait：等待协程结束，直到来自 Go 方法的所有函数调用都返回，然后返回其中的第一个非零错误（如果有的话）。

结合其特性能够非常便捷的针对多 goroutine 进行错误处理：

```golang
func main() {
	g := new(errgroup.Group)
	var urls = []string{
		"http://www.golang.org/",
		"https://golang2.eddycjy.com/",
		"https://eddycjy.com/",
	}
	for _, url := range urls {
		url := url
		g.Go(func() error {
			resp, err := http.Get(url)
			if err == nil {
				resp.Body.Close()
			}
			return err
		})
	}
	if err := g.Wait(); err == nil {
		fmt.Println("Successfully fetched all URLs.")
	} else {
		fmt.Printf("Errors: %+v", err)
	}
}
```

在上述代码中，其表现的是爬虫的案例。每一个计划新起的 goroutine 都直接使用 `Group.Go` 方法。在等待和错误上，直接调用 `Group.Wait` 方法就可以了。

使用标准库 `sync/errgroup` 这种方法的好处就是不需要关注非业务逻辑的控制代码，比较省心省力。

## 进阶使用

在真实的工程代码中，我们还可以基于 `sync/errgroup` 实现一个 http server 的启动和关闭 ，以及 linux signal 信号的注册和处理。以此保证能够实现一个 http server 退出，全部注销退出。

参考代码（@via 毛老师）如下：

```golang
func main() {
	g, ctx := errgroup.WithContext(context.Background())
	svr := http.NewServer()
	// http server
	g.Go(func() error {
		fmt.Println("http")
		go func() {
			<-ctx.Done()
			fmt.Println("http ctx done")
			svr.Shutdown(context.TODO())
		}()
		return svr.Start()
	})

	// signal
	g.Go(func() error {
		exitSignals := []os.Signal{os.Interrupt, syscall.SIGTERM, syscall.SIGQUIT, syscall.SIGINT} // SIGTERM is POSIX specific
		sig := make(chan os.Signal, len(exitSignals))
		signal.Notify(sig, exitSignals...)
		for {
			fmt.Println("signal")
			select {
			case <-ctx.Done():
				fmt.Println("signal ctx done")
				return ctx.Err()
			case <-sig:
				// do something
				return nil
			}
		}
	})

	// inject error
	g.Go(func() error {
		fmt.Println("inject")
		time.Sleep(time.Second)
		fmt.Println("inject finish")
		return errors.New("inject error")
	})

	err := g.Wait() // first error return
	fmt.Println(err)
}
```

内部基础框架有非常有这种代码，有兴趣的可以自己模仿着写一遍，收货会很多。

## 总结

在 Go 语言中 goroutine 是非常常用的一种方法，为此我们需要更了解 goroutine 配套的上下游（像是 context、error 处理等），应该如何用什么来保证。

再在团队中形成一定的共识和规范，这么工程代码阅读起来就会比较的舒适，一些很坑的隐藏 BUG 也会少很多 ：）

================================================
FILE: content/posts/go/goroutine-leak.md
================================================
---
title: "跟面试官聊 Goroutine 泄露的 6 种方法，真刺激！"
date: 2021-06-11T12:54:49+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天分享 Go 群友提问的文章时，有读者在朋友圈下提到，希望我能够针对 Goroutine 泄露这块进行讲解，他在面试的时候经常被问到。

今天的男主角，就是 Go 语言的著名品牌标识 Goroutine，一个随随便便就能开几十万个快车进车道的大杀器。

```golang
    for {
        go func() {}()
    }
```
本文会聚焦于 Goroutine 泄露的 N 种方法，进行详解和说明。

## 为什么要问

面试官为啥会问 Goroutine（协程）泄露这种奇特的问题呢？

可以猜测是：

- Goroutine 实在是使用门槛实在是太低了，随手就一个就能起，出现了不少滥用的情况。例如：并发 map。
- Goroutine 本身在 Go 语言的标准库、复合类型、底层源码中应用广泛。例如：HTTP Server 对每一个请求的处理就是一个协程去运行。

很多 Go 工程在线上出事故时，基本 Goroutine 的关联，大家都会作为救火队长，风风火火的跑去看指标、看日志，通过 PProf 采集 Goroutine 运行情况等。

自然他也就是最受瞩目的那颗 “星” 了，所以在日常面试中，被问几率也就极高了。

## Goroutine 泄露

了解清楚大家爱问的原因后，我们开始对 Goroutine 泄露的 N 种方法进行研究，希望通过前人留下的 “坑”，了解其原理和避开这些问题。

泄露的原因大多集中在：
- Goroutine 内正在进行 channel/mutex 等读写操作，但由于逻辑问题，某些情况下会被一直阻塞。
- Goroutine 内的业务逻辑进入死循环，资源一直无法释放。
- Goroutine 内的业务逻辑进入长时间等待，有不断新增的 Goroutine 进入等待。

接下来我会引用在网上冲浪收集到的一些 Goroutine 泄露例子（会在文末参考注明出处）。

### channel 使用不当

Goroutine+Channel 是最经典的组合，因此不少泄露都出现于此。

最经典的就是上面提到的 channel 进行读写操作时的逻辑问题。

#### 发送不接收

第一个例子：

```golang
func main() {
    for i := 0; i < 4; i++ {
        queryAll()
        fmt.Printf("goroutines: %d\n", runtime.NumGoroutine())
    }
}

func queryAll() int {
    ch := make(chan int)
    for i := 0; i < 3; i++ {
        go func() { ch <- query() }()
	    }
    return <-ch
}

func query() int {
    n := rand.Intn(100)
    time.Sleep(time.Duration(n) * time.Millisecond)
    return n
}
```

输出结果：

```
goroutines: 3
goroutines: 5
goroutines: 7
goroutines: 9
```

在这个例子中，我们调用了多次 `queryAll` 方法，并在 `for` 循环中利用 Goroutine 调用了 `query` 方法。其重点在于调用 `query` 方法后的结果会写入 `ch` 变量中，接收成功后再返回 `ch` 变量。 

最后可看到输出的 goroutines 数量是在不断增加的，每次多 2 个。也就是每调用一次，都会泄露 Goroutine。

原因在于 channel 均已经发送了（每次发送 3 个），但是在接收端并没有接收完全（只返回 1 个 ch），所诱发的 Goroutine 泄露。

#### 接收不发送

第二个例子：

```golang
func main() {
    defer func() {
        fmt.Println("goroutines: ", runtime.NumGoroutine())
    }()

    var ch chan struct{}
    go func() {
        ch <- struct{}{}
    }()
    
    time.Sleep(time.Second)
}
```

输出结果：

```
goroutines:  2
```

在这个例子中，与 “发送不接收” 两者是相对的，channel 接收了值，但是不发送的话，同样会造成阻塞。

但在实际业务场景中，一般更复杂。基本是一大堆业务逻辑里，有一个 channel 的读写操作出现了问题，自然就阻塞了。

#### nil channel

第三个例子：

```golang
func main() {
    defer func() {
        fmt.Println("goroutines: ", runtime.NumGoroutine())
    }()

    var ch chan int
    go func() {
        <-ch
    }()
    
    time.Sleep(time.Second)
}
```

输出结果：

```
goroutines:  2
```

在这个例子中，可以得知 channel 如果忘记初始化，那么无论你是读，还是写操作，都会造成阻塞。

正常的初始化姿势是：

```golang
    ch := make(chan int)
    go func() {
        <-ch
    }()
    ch <- 0
    time.Sleep(time.Second)
```

调用 `make` 函数进行初始化。

### 奇怪的慢等待

第四个例子：

```golang
func main() {
    for {
        go func() {
            _, err := http.Get("https://www.xxx.com/")
            if err != nil {
                fmt.Printf("http.Get err: %v\n", err)
            }
            // do something...
    }()

    time.Sleep(time.Second * 1)
    fmt.Println("goroutines: ", runtime.NumGoroutine())
	}
}
```

输出结果：

```
goroutines:  5
goroutines:  9
goroutines:  13
goroutines:  17
goroutines:  21
goroutines:  25
...
```

在这个例子中，展示了一个 Go 语言中经典的事故场景。也就是一般我们会在应用程序中去调用第三方服务的接口。

但是第三方接口，有时候会很慢，久久不返回响应结果。恰好，Go 语言中默认的 `http.Client` 是没有设置超时时间的。

因此就会导致一直阻塞，一直阻塞就一直爽，Goroutine 自然也就持续暴涨，不断泄露，最终占满资源，导致事故。

在 Go 工程中，我们一般建议至少对 `http.Client` 设置超时时间：

```golang
    httpClient := http.Client{
        Timeout: time.Second * 15,
    }
```
并且要做限流、熔断等措施，以防突发流量造成依赖崩塌，依然吃 P0。

### 互斥锁忘记解锁

第五个例子：

```golang
func main() {
    total := 0
    defer func() {
        time.Sleep(time.Second)
        fmt.Println("total: ", total)
        fmt.Println("goroutines: ", runtime.NumGoroutine())
	}()

    var mutex sync.Mutex
    for i := 0; i < 10; i++ {
        go func() {
            mutex.Lock()
            total += 1
        }()
    }
}
```

输出结果：

```
total:  1
goroutines:  10
```

在这个例子中，第一个互斥锁 `sync.Mutex` 加锁了，但是他可能在处理业务逻辑，又或是忘记 `Unlock` 了。

因此导致后面的所有 `sync.Mutex` 想加锁，却因未释放又都阻塞住了。一般在 Go 工程中，我们建议如下写法：

```golang
    var mutex sync.Mutex
    for i := 0; i < 10; i++ {
        go func() {
            mutex.Lock()
            defer mutex.Unlock()
            total += 1
    }()
    }
```

### 同步锁使用不当

第六个例子：

```golang
func handle(v int) {
    var wg sync.WaitGroup
    wg.Add(5)
    for i := 0; i < v; i++ {
        fmt.Println("脑子进煎鱼了")
        wg.Done()
    }
    wg.Wait()
}

func main() {
    defer func() {
        fmt.Println("goroutines: ", runtime.NumGoroutine())
    }()

    go handle(3)
    time.Sleep(time.Second)
}
```

在这个例子中，我们调用了同步编排 `sync.WaitGroup`，模拟了一遍我们会从外部传入循环遍历的控制变量。

但由于 `wg.Add` 的数量与 `wg.Done` 数量并不匹配，因此在调用 `wg.Wait` 方法后一直阻塞等待。

在 Go 工程中使用，我们会建议如下写法：

```golang
    var wg sync.WaitGroup
    for i := 0; i < v; i++ {
        wg.Add(1)
        defer wg.Done()
        fmt.Println("脑子进煎鱼了")
    }
    wg.Wait()
```

## 排查方法

我们可以调用 `runtime.NumGoroutine` 方法来获取 Goroutine 的运行数量，进行前后一比较，就能知道有没有泄露了。

但在业务服务的运行场景中，Goroutine 内导致的泄露，大多数处于生产、测试环境，因此更多的是使用 PProf：

```golang
import (
    "net/http"
     _ "net/http/pprof"
)

http.ListenAndServe("localhost:6060", nil))
```

只要我们调用 `http://localhost:6060/debug/pprof/goroutine?debug=1`，PProf 会返回所有带有堆栈跟踪的 Goroutine 列表。

也可以利用 PProf 的其他特性进行综合查看和分析，这块参考我之前写的《Go 大杀器之性能剖析 PProf》，基本是全村最全的教程了。

## 总结

在今天这篇文章中，我们针对 Goroutine 泄露的 N 种常见的方式方法进行了一一分析，虽说看起来都是比较基础的场景。

但结合在实际业务代码中，就是一大坨中的某个细节导致全盘皆输了，希望上面几个案例能够给大家带来警惕。

而面试官爱问，怕不是自己踩过许多坑，也希望进来的同僚，也是身经百战了。

靠谱的工程师，而非只是八股工程师。

## 参考

- 波罗学大佬的《[Go 笔记之如何防止 goroutine 泄露](https://zhuanlan.zhihu.com/p/74090074)》
- 二斗斗的《[怎么看待Goroutine 泄露](https://zhuanlan.zhihu.com/p/139689803)》

================================================
FILE: content/posts/go/grpc/2018-09-22-install.md
================================================
---

title:      "「连载一」gRPC及相关介绍"
date:       2018-09-22 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

项目地址：https://github.com/EDDYCJY/go-grpc-example

作为开篇章，将会介绍 gRPC 相关的一些知识。简单来讲 gRPC 是一个 基于 HTTP/2 协议设计的 RPC 框架，它采用了 Protobuf 作为 IDL

你是否有过疑惑，它们都是些什么？本文将会介绍一些常用的知识和概念，更详细的会给出手册地址去深入

## 一、RPC

### 什么是 RPC

RPC 代指远程过程调用（Remote Procedure Call），它的调用包含了传输协议和编码（对象序列号）协议等等。允许运行于一台计算机的程序调用另一台计算机的子程序，而开发人员无需额外地为这个交互作用编程

#### 实际场景：

有两台服务器，分别是 A、B。在 A 上的应用 C 想要调用 B 服务器上的应用 D，它们可以直接本地调用吗？  
答案是不能的，但走 RPC 的话，十分方便。因此常有人称使用 RPC，就跟本地调用一个函数一样简单

### RPC 框架

我认为，一个完整的 RPC 框架，应包含负载均衡、服务注册和发现、服务治理等功能，并具有可拓展性便于流量监控系统等接入  
那么它才算完整的，当然了。有些较单一的 RPC 框架，通过组合多组件也能达到这个标准

你认为呢？

### 常见 RPC 框架

- [gRPC](https://grpc.io/)
- [Thrift](https://github.com/apache/thrift)
- [Rpcx](https://github.com/smallnest/rpcx)
- [Dubbo](https://github.com/apache/incubator-dubbo)

### 比较一下

| \      | 跨语言 | 多 IDL | 服务治理 | 注册中心 | 服务管理 |
| ------ | ------ | ------ | -------- | -------- | -------- |
| gRPC   | √      | ×      | ×        | ×        | ×        |
| Thrift | √      | ×      | ×        | ×        | ×        |
| Rpcx   | ×      | √      | √        | √        | √        |
| Dubbo  | ×      | √      | √        | √        | √        |

### 为什么要 RPC

简单、通用、安全、效率

### RPC 可以基于 HTTP 吗

RPC 是代指远程过程调用，是可以基于 HTTP 协议的

肯定会有人说效率优势，我可以告诉你，那是基于 HTTP/1.1 来讲的，HTTP/2 优化了许多问题（当然也存在新的问题），所以你看到了本文的主题 gRPC

## 二、Protobuf

### 介绍

Protocol Buffers 是一种与语言、平台无关，可扩展的序列化结构化数据的方法，常用于通信协议，数据存储等等。相较于 JSON、XML，它更小、更快、更简单，因此也更受开发人员的青眯

### 语法

```go
syntax = "proto3";

service SearchService {
    rpc Search (SearchRequest) returns (SearchResponse);
}

message SearchRequest {
  string query = 1;
  int32 page_number = 2;
  int32 result_per_page = 3;
}

message SearchResponse {
    ...
}
```

1、第一行（非空的非注释行）声明使用 `proto3` 语法。如果不声明，将默认使用 `proto2` 语法。同时我建议用 v2 还是 v3，都应当声明其使用的版本

2、定义 `SearchService` RPC 服务，其包含 RPC 方法 `Search`，入参为 `SearchRequest` 消息，出参为 `SearchResponse` 消息

3、定义 `SearchRequest`、`SearchResponse` 消息，前者定义了三个字段，每一个字段包含三个属性：类型、字段名称、字段编号

4、Protobuf 编译器会根据选择的语言不同，生成相应语言的 Service Interface Code 和 Stubs

最后，这里只是简单的语法介绍，详细的请右拐 [
Language Guide (proto3)](https://developers.google.com/protocol-buffers/docs/proto3)

### 数据类型

| .proto Type | C++ Type | Java Type  | Go Type | PHP Type       |
| ----------- | -------- | ---------- | ------- | -------------- |
| double      | double   | double     | float64 | float          |
| float       | float    | float      | float32 | float          |
| int32       | int32    | int        | int32   | integer        |
| int64       | int64    | long       | int64   | integer/string |
| uint32      | uint32   | int        | uint32  | integer        |
| uint64      | uint64   | long       | uint64  | integer/string |
| sint32      | int32    | int        | int32   | integer        |
| sint64      | int64    | long       | int64   | integer/string |
| fixed32     | uint32   | int        | uint32  | integer        |
| fixed64     | uint64   | long       | uint64  | integer/string |
| sfixed32    | int32    | int        | int32   | integer        |
| sfixed64    | int64    | long       | int64   | integer/string |
| bool        | bool     | boolean    | bool    | boolean        |
| string      | string   | String     | string  | string         |
| bytes       | string   | ByteString | []byte  | string         |

### v2 和 v3 主要区别

- 删除原始值字段的字段存在逻辑
- 删除 required 字段
- 删除 optional 字段，默认就是
- 删除 default 字段
- 删除扩展特性，新增 Any 类型来替代它
- 删除 unknown 字段的支持
- 新增 [JSON Mapping](https://developers.google.com/protocol-buffers/docs/proto3#json)
- 新增 Map 类型的支持
- 修复 enum 的 unknown 类型
- repeated 默认使用 packed 编码
- 引入了新的语言实现（C＃，JavaScript，Ruby，Objective-C）

以上是日常涉及的常见功能，如果还想详细了解可阅读 [Protobuf Version 3.0.0](https://github.com/protocolbuffers/protobuf/releases?after=v3.2.1)

### 相较 Protobuf，为什么不使用 XML？

- 更简单
- 数据描述文件只需原来的 1/10 至 1/3
- 解析速度是原来的 20 倍至 100 倍
- 减少了二义性
- 生成了更易使用的数据访问类

## 三、gRPC

### 介绍

gRPC 是一个高性能、开源和通用的 RPC 框架，面向移动和 HTTP/2 设计

#### 多语言

- C++
- C#
- Dart
- Go
- Java
- Node.js
- Objective-C
- PHP
- Python
- Ruby

#### 特点

1、HTTP/2

2、Protobuf

3、客户端、服务端基于同一份 IDL

4、移动网络的良好支持

5、支持多语言

### 概览

![image](https://image.eddycjy.com/7dcac5be0a34636c699025368242d3f3.png)

### 讲解

1、客户端（gRPC Sub）调用 A 方法，发起 RPC 调用

2、对请求信息使用 Protobuf 进行对象序列化压缩（IDL）

3、服务端（gRPC Server）接收到请求后，解码请求体，进行业务逻辑处理并返回

4、对响应结果使用 Protobuf 进行对象序列化压缩（IDL）

5、客户端接受到服务端响应，解码请求体。回调被调用的 A 方法，唤醒正在等待响应（阻塞）的客户端调用并返回响应结果

### 示例

在这一小节，将简单的给大家展示 gRPC 的客户端和服务端的示例代码，希望大家先有一个基础的印象，将会在下一章节详细介绍 🤔

#### 构建和启动服务端

```go
lis, err := net.Listen("tcp", fmt.Sprintf(":%d", *port))
if err != nil {
        log.Fatalf("failed to listen: %v", err)
}

grpcServer := grpc.NewServer()
...
pb.RegisterSearchServer(grpcServer, &SearchServer{})
grpcServer.Serve(lis)
```

1、监听指定 TCP 端口，用于接受客户端请求

2、创建 gRPC Server 的实例对象

3、gRPC Server 内部服务和路由的注册

4、Serve() 调用服务器以执行阻塞等待，直到进程被终止或被 Stop() 调用

#### 创建客户端

```go
var opts []grpc.DialOption
...
conn, err := grpc.Dial(*serverAddr, opts...)
if err != nil {
    log.Fatalf("fail to dial: %v", err)
}

defer conn.Close()
client := pb.NewSearchClient(conn)
...
```

1、创建 gRPC Channel 与 gRPC Server 进行通信（需服务器地址和端口作为参数）

2、设置 DialOptions 凭证（例如，TLS，GCE 凭据，JWT 凭证）

3、创建 Search Client Stub

4、调用对应的服务方法

## 思考题

1、什么场景下不适合使用 Protobuf，而适合使用 JSON、XML？

2、Protobuf 一节中提到的 packed 编码，是什么？

## 总结

在开篇内容中，我利用了尽量简短的描述给你介绍了接下来所必须、必要的知识点
希望你能够有所收获，建议能到我给的参考资料处进行深入学习，是最好的了

## 参考资料

- [Protocol Buffers](https://developers.google.com/protocol-buffers/docs/proto3)
- [gRPC](https://grpc.io/docs/)


================================================
FILE: content/posts/go/grpc/2018-09-23-client-and-server.md
================================================
---

title:      "「连载二」gRPC Client and Server"
date:       2018-09-23 12:30:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

本章节将使用 Go 来编写 gRPC Server 和 Client，让其互相通讯。在此之上会使用到如下库：

- google.golang.org/grpc
- github.com/golang/protobuf/protoc-gen-go

## 安装

### gRPC

```
go get -u google.golang.org/grpc
```

### Protocol Buffers v3

```
wget https://github.com/google/protobuf/releases/download/v3.5.1/protobuf-all-3.5.1.zip
unzip protobuf-all-3.5.1.zip
cd protobuf-3.5.1/
./configure
make
make install
```

检查是否安装成功

```
protoc --version
```

若出现以下错误，执行 `ldconfig` 命名就能解决这问题

```
protoc: error while loading shared libraries: libprotobuf.so.15: cannot open shared object file: No such file or directory
```

### Protoc Plugin

```
go get -u github.com/golang/protobuf/protoc-gen-go
```

安装环境若有问题，可参考我先前的文章 [《介绍与环境安装》](https://segmentfault.com/a/1190000013339403) 内有详细介绍，不再赘述

## gRPC

本小节开始正式编写 gRPC 相关的程序，一起上车吧 😄

### 图示

![image](https://image.eddycjy.com/415d9544fce1e774e1095ab99b6cc015.png)

### 目录结构

```
$ tree go-grpc-example
go-grpc-example
├── client
├── proto
│   └── search.proto
└── server.go
```

### IDL

#### 编写

在 proto 文件夹下的 search.proto 文件中，写入如下内容：

```
syntax = "proto3";

package proto;

service SearchService {
    rpc Search(SearchRequest) returns (SearchResponse) {}
}

message SearchRequest {
    string request = 1;
}

message SearchResponse {
    string response = 1;
}
```

#### 生成

在 proto 文件夹下执行如下命令：

```
$ protoc --go_out=plugins=grpc:. *.proto
```

- plugins=plugin1+plugin2：指定要加载的子插件列表

我们定义的 proto 文件是涉及了 RPC 服务的，而默认是不会生成 RPC 代码的，因此需要给出 `plugins` 参数传递给 `protoc-gen-go`，告诉它，请支持 RPC（这里指定了 gRPC）

- --go_out=.：设置 Go 代码输出的目录

该指令会加载 protoc-gen-go 插件达到生成 Go 代码的目的，生成的文件以 .pb.go 为文件后缀

- : （冒号）

冒号充当分隔符的作用，后跟所需要的参数集。如果这处不涉及 RPC，命令可简化为：

```
$ protoc --go_out=. *.proto
```

注：建议你看看两条命令生成的 .pb.go 文件，分别有什么区别

#### 生成后

执行完毕命令后，将得到一个 .pb.go 文件，文件内容如下：

```go
type SearchRequest struct {
	Request              string   `protobuf:"bytes,1,opt,name=request" json:"request,omitempty"`
	XXX_NoUnkeyedLiteral struct{} `json:"-"`
	XXX_unrecognized     []byte   `json:"-"`
	XXX_sizecache        int32    `json:"-"`
}

func (m *SearchRequest) Reset()         { *m = SearchRequest{} }
func (m *SearchRequest) String() string { return proto.CompactTextString(m) }
func (*SearchRequest) ProtoMessage()    {}
func (*SearchRequest) Descriptor() ([]byte, []int) {
	return fileDescriptor_search_8b45f79ee13ff6a3, []int{0}
}

func (m *SearchRequest) GetRequest() string {
	if m != nil {
		return m.Request
	}
	return ""
}
```

通过阅读这一部分代码，可以知道主要涉及如下方面：

- 字段名称从小写下划线转换为大写驼峰模式（字段导出）
- 生成一组 Getters 方法，能便于处理一些空指针取值的情况
- ProtoMessage 方法实现 proto.Message 的接口
- 生成 Rest 方法，便于将 Protobuf 结构体恢复为零值
- Repeated 转换为切片

```go
type SearchRequest struct {
	Request              string   `protobuf:"bytes,1,opt,name=request" json:"request,omitempty"`
}

func (*SearchRequest) Descriptor() ([]byte, []int) {
	return fileDescriptor_search_8b45f79ee13ff6a3, []int{0}
}

type SearchResponse struct {
	Response             string   `protobuf:"bytes,1,opt,name=response" json:"response,omitempty"`
}

func (*SearchResponse) Descriptor() ([]byte, []int) {
	return fileDescriptor_search_8b45f79ee13ff6a3, []int{1}
}

...

func init() { proto.RegisterFile("search.proto", fileDescriptor_search_8b45f79ee13ff6a3) }

var fileDescriptor_search_8b45f79ee13ff6a3 = []byte{
	// 131 bytes of a gzipped FileDescriptorProto
	0x1f, 0x8b, 0x08, 0x00, 0x00, 0x00, 0x00, 0x00, 0x02, 0xff, 0xe2, 0xe2, 0x29, 0x4e, 0x4d, 0x2c,
	0x4a, 0xce, 0xd0, 0x2b, 0x28, 0xca, 0x2f, 0xc9, 0x17, 0x62, 0x05, 0x53, 0x4a, 0x9a, 0x5c, 0xbc,
	0xc1, 0x60, 0xe1, 0xa0, 0xd4, 0xc2, 0xd2, 0xd4, 0xe2, 0x12, 0x21, 0x09, 0x2e, 0xf6, 0x22, 0x08,
	0x53, 0x82, 0x51, 0x81, 0x51, 0x83, 0x33, 0x08, 0xc6, 0x55, 0xd2, 0xe1, 0xe2, 0x83, 0x29, 0x2d,
	0x2e, 0xc8, 0xcf, 0x2b, 0x4e, 0x15, 0x92, 0xe2, 0xe2, 0x28, 0x82, 0xb2, 0xa1, 0x8a, 0xe1, 0x7c,
	0x23, 0x0f, 0x98, 0xc1, 0xc1, 0xa9, 0x45, 0x65, 0x99, 0xc9, 0xa9, 0x42, 0xe6, 0x5c, 0x6c, 0x10,
	0x01, 0x21, 0x11, 0x88, 0x13, 0xf4, 0x50, 0x2c, 0x96, 0x12, 0x45, 0x13, 0x85, 0x98, 0xa3, 0xc4,
	0x90, 0xc4, 0x06, 0x16, 0x37, 0x06, 0x04, 0x00, 0x00, 0xff, 0xff, 0xf3, 0xba, 0x74, 0x95, 0xc0,
	0x00, 0x00, 0x00,
}
```

而这一部分代码主要是围绕 `fileDescriptor` 进行，在这里 `fileDescriptor_search_8b45f79ee13ff6a3` 表示一个编译后的 proto 文件，而每一个方法都包含 Descriptor 方法，代表着这一个方法在 `fileDescriptor` 中具体的 Message Field

### Server

这一小节将编写 gRPC Server 的基础模板，完成一个方法的调用。对 server.go 写入如下内容：

```go
package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

type SearchService struct{}

func (s *SearchService) Search(ctx context.Context, r *pb.SearchRequest) (*pb.SearchResponse, error) {
	return &pb.SearchResponse{Response: r.GetRequest() + " Server"}, nil
}

const PORT = "9001"

func main() {
	server := grpc.NewServer()
	pb.RegisterSearchServiceServer(server, &SearchService{})

	lis, err := net.Listen("tcp", ":"+PORT)
	if err != nil {
		log.Fatalf("net.Listen err: %v", err)
	}

	server.Serve(lis)
}
```

- 创建 gRPC Server 对象，你可以理解为它是 Server 端的抽象对象
- 将 SearchService（其包含需要被调用的服务端接口）注册到 gRPC Server 的内部注册中心。这样可以在接受到请求时，通过内部的服务发现，发现该服务端接口并转接进行逻辑处理
- 创建 Listen，监听 TCP 端口
- gRPC Server 开始 lis.Accept，直到 Stop 或 GracefulStop

### Client

接下来编写 gRPC Go Client 的基础模板，打开 client/client.go 文件，写入以下内容：

```go
package main

import (
	"context"
	"log"

	"google.golang.org/grpc"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

const PORT = "9001"

func main() {
	conn, err := grpc.Dial(":"+PORT, grpc.WithInsecure())
	if err != nil {
		log.Fatalf("grpc.Dial err: %v", err)
	}
	defer conn.Close()

	client := pb.NewSearchServiceClient(conn)
	resp, err := client.Search(context.Background(), &pb.SearchRequest{
		Request: "gRPC",
	})
	if err != nil {
		log.Fatalf("client.Search err: %v", err)
	}

	log.Printf("resp: %s", resp.GetResponse())
}
```

- 创建与给定目标（服务端）的连接交互
- 创建 SearchService 的客户端对象
- 发送 RPC 请求，等待同步响应，得到回调后返回响应结果
- 输出响应结果

## 验证

### 启动 Server

```sh
$ pwd
$GOPATH/github.com/EDDYCJY/go-grpc-example
$ go run server.go
```

### 启动 Client

```sh
$ pwd
$GOPATH/github.com/EDDYCJY/go-grpc-example/client
$ go run client.go
2018/09/23 11:06:23 resp: gRPC Server
```

## 总结

在本章节，我们对 Protobuf、gRPC Client/Server 分别都进行了介绍。希望你结合文中讲述内容再写一个 Demo 进行深入了解，肯定会更棒 🤔

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

================================================
FILE: content/posts/go/grpc/2018-09-24-stream-client-server.md
================================================
---

title:      "「连载三」gRPC Streaming, Client and Server"
date:       2018-09-24 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

本章节将介绍 gRPC 的流式，分为三种类型：

- Server-side streaming RPC：服务器端流式 RPC
- Client-side streaming RPC：客户端流式 RPC
- Bidirectional streaming RPC：双向流式 RPC

## 流

任何技术，因为有痛点，所以才有了存在的必要性。如果您想要了解 gRPC 的流式调用，请继续

### 图

![image](https://image.eddycjy.com/8812038d20ffece377c0e4901c9a9231.png)

gRPC Streaming 是基于 HTTP/2 的，后续章节再进行详细讲解

### 为什么不用 Simple RPC

流式为什么要存在呢，是 Simple RPC 有什么问题吗？通过模拟业务场景，可得知在使用 Simple RPC 时，有如下问题：

- 数据包过大造成的瞬时压力
- 接收数据包时，需要所有数据包都接受成功且正确后，才能够回调响应，进行业务处理（无法客户端边发送，服务端边处理）

### 为什么用 Streaming RPC

- 大规模数据包
- 实时场景

#### 模拟场景

每天早上 6 点，都有一批百万级别的数据集要同从 A 同步到 B，在同步的时候，会做一系列操作（归档、数据分析、画像、日志等）。这一次性涉及的数据量确实大

在同步完成后，也有人马上会去查阅数据，为了新的一天筹备。也符合实时性。

两者相较下，这个场景下更适合使用 Streaming RPC

## gRPC

在讲解具体的 gRPC 流式代码时，会**着重在第一节讲解**，因为三种模式其实是不同的组合。希望你能够注重理解，举一反三，其实都是一样的知识点 👍

### 目录结构

```
$ tree go-grpc-example
go-grpc-example
├── client
│   ├── simple_client
│   │   └── client.go
│   └── stream_client
│       └── client.go
├── proto
│   ├── search.proto
│   └── stream.proto
└── server
    ├── simple_server
    │   └── server.go
    └── stream_server
        └── server.go
```

增加 stream_server、stream_client 存放服务端和客户端文件，proto/stream.proto 用于编写 IDL

### IDL

在 proto 文件夹下的 stream.proto 文件中，写入如下内容：

```
syntax = "proto3";

package proto;

service StreamService {
    rpc List(StreamRequest) returns (stream StreamResponse) {};

    rpc Record(stream StreamRequest) returns (StreamResponse) {};

    rpc Route(stream StreamRequest) returns (stream StreamResponse) {};
}


message StreamPoint {
  string name = 1;
  int32 value = 2;
}

message StreamRequest {
  StreamPoint pt = 1;
}

message StreamResponse {
  StreamPoint pt = 1;
}
```

注意关键字 stream，声明其为一个流方法。这里共涉及三个方法，对应关系为

- List：服务器端流式 RPC
- Record：客户端流式 RPC
- Route：双向流式 RPC

### 基础模板 + 空定义

#### Server

```go
package main

import (
	"log"
	"net"

	"google.golang.org/grpc"

	pb "github.com/EDDYCJY/go-grpc-example/proto"

)

type StreamService struct{}

const (
	PORT = "9002"
)

func main() {
	server := grpc.NewServer()
	pb.RegisterStreamServiceServer(server, &StreamService{})

	lis, err := net.Listen("tcp", ":"+PORT)
	if err != nil {
		log.Fatalf("net.Listen err: %v", err)
	}

	server.Serve(lis)
}

func (s *StreamService) List(r *pb.StreamRequest, stream pb.StreamService_ListServer) error {
	return nil
}

func (s *StreamService) Record(stream pb.StreamService_RecordServer) error {
	return nil
}

func (s *StreamService) Route(stream pb.StreamService_RouteServer) error {
	return nil
}
```

写代码前，建议先将 gRPC Server 的基础模板和接口给空定义出来。若有不清楚可参见上一章节的知识点

#### Client

```go
package main

import (
    "log"

	"google.golang.org/grpc"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

const (
	PORT = "9002"
)

func main() {
	conn, err := grpc.Dial(":"+PORT, grpc.WithInsecure())
	if err != nil {
		log.Fatalf("grpc.Dial err: %v", err)
	}

	defer conn.Close()

	client := pb.NewStreamServiceClient(conn)

	err = printLists(client, &pb.StreamRequest{Pt: &pb.StreamPoint{Name: "gRPC Stream Client: List", Value: 2018}})
	if err != nil {
		log.Fatalf("printLists.err: %v", err)
	}

	err = printRecord(client, &pb.StreamRequest{Pt: &pb.StreamPoint{Name: "gRPC Stream Client: Record", Value: 2018}})
	if err != nil {
		log.Fatalf("printRecord.err: %v", err)
	}

	err = printRoute(client, &pb.StreamRequest{Pt: &pb.StreamPoint{Name: "gRPC Stream Client: Route", Value: 2018}})
	if err != nil {
		log.Fatalf("printRoute.err: %v", err)
	}
}

func printLists(client pb.StreamServiceClient, r *pb.StreamRequest) error {
	return nil
}

func printRecord(client pb.StreamServiceClient, r *pb.StreamRequest) error {
	return nil
}

func printRoute(client pb.StreamServiceClient, r *pb.StreamRequest) error {
	return nil
}
```

### 一、Server-side streaming RPC：服务器端流式 RPC

服务器端流式 RPC，显然是单向流，并代指 Server 为 Stream 而 Client 为普通 RPC 请求

简单来讲就是客户端发起一次普通的 RPC 请求，服务端通过流式响应多次发送数据集，客户端 Recv 接收数据集。大致如图：

![image](https://image.eddycjy.com/b25a47e2f2fb2a8c352a547f7612808b.png)

#### Server

```go
func (s *StreamService) List(r *pb.StreamRequest, stream pb.StreamService_ListServer) error {
	for n := 0; n <= 6; n++ {
		err := stream.Send(&pb.StreamResponse{
			Pt: &pb.StreamPoint{
				Name:  r.Pt.Name,
				Value: r.Pt.Value + int32(n),
			},
		})
		if err != nil {
			return err
		}
	}

	return nil
}
```

在 Server，主要留意 `stream.Send` 方法。它看上去能发送 N 次？有没有大小限制？

```go
type StreamService_ListServer interface {
	Send(*StreamResponse) error
	grpc.ServerStream
}

func (x *streamServiceListServer) Send(m *StreamResponse) error {
	return x.ServerStream.SendMsg(m)
}
```

通过阅读源码，可得知是 protoc 在生成时，根据定义生成了各式各样符合标准的接口方法。最终再统一调度内部的 `SendMsg` 方法，该方法涉及以下过程:

- 消息体（对象）序列化
- 压缩序列化后的消息体
- 对正在传输的消息体增加 5 个字节的 header
- 判断压缩+序列化后的消息体总字节长度是否大于预设的 maxSendMessageSize（预设值为 `math.MaxInt32`），若超出则提示错误
- 写入给流的数据集

#### Client

```go
func printLists(client pb.StreamServiceClient, r *pb.StreamRequest) error {
	stream, err := client.List(context.Background(), r)
	if err != nil {
		return err
	}

	for {
		resp, err := stream.Recv()
		if err == io.EOF {
			break
		}
		if err != nil {
			return err
		}

		log.Printf("resp: pj.name: %s, pt.value: %d", resp.Pt.Name, resp.Pt.Value)
	}

	return nil
}
```

在 Client，主要留意 `stream.Recv()` 方法。什么情况下 `io.EOF` ？什么情况下存在错误信息呢?

```go
type StreamService_ListClient interface {
	Recv() (*StreamResponse, error)
	grpc.ClientStream
}

func (x *streamServiceListClient) Recv() (*StreamResponse, error) {
	m := new(StreamResponse)
	if err := x.ClientStream.RecvMsg(m); err != nil {
		return nil, err
	}
	return m, nil
}
```

RecvMsg 会从流中读取完整的 gRPC 消息体，另外通过阅读源码可得知：

（1）RecvMsg 是阻塞等待的

（2）RecvMsg 当流成功/结束（调用了 Close）时，会返回 `io.EOF`

（3）RecvMsg 当流出现任何错误时，流会被中止，错误信息会包含 RPC 错误码。而在 RecvMsg 中可能出现如下错误：

- io.EOF
- io.ErrUnexpectedEOF
- transport.ConnectionError
- google.golang.org/grpc/codes

同时需要注意，默认的 MaxReceiveMessageSize 值为 1024 _ 1024 _ 4，建议不要超出

#### 验证

运行 stream_server/server.go：

```
$ go run server.go
```

运行 stream_client/client.go：

```
$ go run client.go
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2018
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2019
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2020
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2021
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2022
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2023
2018/09/24 16:18:25 resp: pj.name: gRPC Stream Client: List, pt.value: 2024
```

### 二、Client-side streaming RPC：客户端流式 RPC

客户端流式 RPC，单向流，客户端通过流式发起**多次** RPC 请求给服务端，服务端发起**一次**响应给客户端，大致如图：

![image](https://image.eddycjy.com/97473884d939ec91d6cdf53090bef92e.png)

#### Server

```go
func (s *StreamService) Record(stream pb.StreamService_RecordServer) error {
	for {
		r, err := stream.Recv()
		if err == io.EOF {
			return stream.SendAndClose(&pb.StreamResponse{Pt: &pb.StreamPoint{Name: "gRPC Stream Server: Record", Value: 1}})
		}
		if err != nil {
			return err
		}

		log.Printf("stream.Recv pt.name: %s, pt.value: %d", r.Pt.Name, r.Pt.Value)
	}

	return nil
}
```

多了一个从未见过的方法 `stream.SendAndClose`，它是做什么用的呢？

在这段程序中，我们对每一个 Recv 都进行了处理，当发现 `io.EOF` (流关闭) 后，需要将最终的响应结果发送给客户端，同时关闭正在另外一侧等待的 Recv

#### Client

```go
func printRecord(client pb.StreamServiceClient, r *pb.StreamRequest) error {
	stream, err := client.Record(context.Background())
	if err != nil {
		return err
	}

	for n := 0; n < 6; n++ {
		err := stream.Send(r)
		if err != nil {
			return err
		}
	}

	resp, err := stream.CloseAndRecv()
	if err != nil {
		return err
	}

	log.Printf("resp: pj.name: %s, pt.value: %d", resp.Pt.Name, resp.Pt.Value)

	return nil
}
```

`stream.CloseAndRecv` 和 `stream.SendAndClose` 是配套使用的流方法，相信聪明的你已经秒懂它的作用了

#### 验证

重启 stream_server/server.go，再次运行 stream_client/client.go：

##### stream_client：

```
$ go run client.go
2018/09/24 16:23:03 resp: pj.name: gRPC Stream Server: Record, pt.value: 1
```

##### stream_server：

```
$ go run server.go
2018/09/24 16:23:03 stream.Recv pt.name: gRPC Stream Client: Record, pt.value: 2018
2018/09/24 16:23:03 stream.Recv pt.name: gRPC Stream Client: Record, pt.value: 2018
2018/09/24 16:23:03 stream.Recv pt.name: gRPC Stream Client: Record, pt.value: 2018
2018/09/24 16:23:03 stream.Recv pt.name: gRPC Stream Client: Record, pt.value: 2018
2018/09/24 16:23:03 stream.Recv pt.name: gRPC Stream Client: Record, pt.value: 2018
2018/09/24 16:23:03 stream.Recv pt.name: gRPC Stream Client: Record, pt.value: 2018
```

### 三、Bidirectional streaming RPC：双向流式 RPC

双向流式 RPC，顾名思义是双向流。由客户端以流式的方式发起请求，服务端同样以流式的方式响应请求

首个请求一定是 Client 发起，但具体交互方式（谁先谁后、一次发多少、响应多少、什么时候关闭）根据程序编写的方式来确定（可以结合协程）

假设该双向流是**按顺序发送**的话，大致如图：

![image](https://image.eddycjy.com/ab80297cd6715048a235e0c9b0f36091.png)

还是要强调，双向流变化很大，因程序编写的不同而不同。**双向流图示无法适用不同的场景**

#### Server

```go
func (s *StreamService) Route(stream pb.StreamService_RouteServer) error {
	n := 0
	for {
		err := stream.Send(&pb.StreamResponse{
			Pt: &pb.StreamPoint{
				Name:  "gPRC Stream Client: Route",
				Value: int32(n),
			},
		})
		if err != nil {
			return err
		}

		r, err := stream.Recv()
		if err == io.EOF {
			return nil
		}
		if err != nil {
			return err
		}

		n++

		log.Printf("stream.Recv pt.name: %s, pt.value: %d", r.Pt.Name, r.Pt.Value)
	}

	return nil
}
```

#### Client

```go
func printRoute(client pb.StreamServiceClient, r *pb.StreamRequest) error {
	stream, err := client.Route(context.Background())
	if err != nil {
		return err
	}

	for n := 0; n <= 6; n++ {
		err = stream.Send(r)
		if err != nil {
			return err
		}

		resp, err := stream.Recv()
		if err == io.EOF {
			break
		}
		if err != nil {
			return err
		}

		log.Printf("resp: pj.name: %s, pt.value: %d", resp.Pt.Name, resp.Pt.Value)
	}

	stream.CloseSend()

	return nil
}
```

#### 验证

重启 stream_server/server.go，再次运行 stream_client/client.go：

##### stream_server

```
$ go run server.go
2018/09/24 16:29:43 stream.Recv pt.name: gRPC Stream Client: Route, pt.value: 2018
2018/09/24 16:29:43 stream.Recv pt.name: gRPC Stream Client: Route, pt.value: 2018
2018/09/24 16:29:43 stream.Recv pt.name: gRPC Stream Client: Route, pt.value: 2018
2018/09/24 16:29:43 stream.Recv pt.name: gRPC Stream Client: Route, pt.value: 2018
2018/09/24 16:29:43 stream.Recv pt.name: gRPC Stream Client: Route, pt.value: 2018
2018/09/24 16:29:43 stream.Recv pt.name: gRPC Stream Client: Route, pt.value: 2018
```

##### stream_client

```
$ go run client.go
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 0
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 1
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 2
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 3
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 4
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 5
2018/09/24 16:29:43 resp: pj.name: gPRC Stream Client: Route, pt.value: 6
```

## 总结

在本文共介绍了三类流的交互方式，可以根据实际的业务场景去选择合适的方式。会事半功倍哦 🎑

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

================================================
FILE: content/posts/go/grpc/2018-10-07-grpc-tls.md
================================================
---

title:      "「连载四」TLS 证书认证"
date:       2018-10-07 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

在前面的章节里，我们介绍了 gRPC 的四种 API 使用方式。是不是很简单呢 😀

此时存在一个安全问题，先前的例子中 gRPC Client/Server 都是明文传输的，会不会有被窃听的风险呢？

从结论上来讲，是有的。在明文通讯的情况下，你的请求就是裸奔的，有可能被第三方恶意篡改或者伪造为“非法”的数据

## 抓个包

![image](https://image.eddycjy.com/15e68df2ba9aa7cace3e26e35c79f200.jpg)

![image](https://image.eddycjy.com/ebebd3ea7d306ad2fcd311f1d8b46cc0.jpg)

嗯，明文传输无误。这是有问题的，接下将改造我们的 gRPC，以便于解决这个问题 😤

## 证书生成

### 私钥

```
openssl ecparam -genkey -name secp384r1 -out server.key
```

### 自签公钥

```
openssl req -new -x509 -sha256 -key server.key -out server.pem -days 3650
```

#### 填写信息

```
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:go-grpc-example
Email Address []:
```

### 生成完毕

生成证书结束后，将证书相关文件放到 conf/ 下，目录结构：

```
$ tree go-grpc-example
go-grpc-example
├── client
├── conf
│   ├── server.key
│   └── server.pem
├── proto
└── server
    ├── simple_server
    └── stream_server
```

由于本文偏向 gRPC，详解可参见 [《制作证书》](https://segmentfault.com/a/1190000013408485#articleHeader3)。后续番外可能会展开细节描述 👌

## 为什么之前不需要证书

在 simple_server 中，为什么“啥事都没干”就能在不需要证书的情况下运行呢？

### Server

```go
grpc.NewServer()
```

在服务端显然没有传入任何 DialOptions

### Client

```go
conn, err := grpc.Dial(":"+PORT, grpc.WithInsecure())
```

在客户端留意到 `grpc.WithInsecure()` 方法

```go
func WithInsecure() DialOption {
	return newFuncDialOption(func(o *dialOptions) {
		o.insecure = true
	})
}
```

在方法内可以看到 `WithInsecure` 返回一个 `DialOption`，并且它最终会通过读取设置的值来禁用安全传输

那么它“最终”又是在哪里处理的呢，我们把视线移到 `grpc.Dial()` 方法内

```go
func DialContext(ctx context.Context, target string, opts ...DialOption) (conn *ClientConn, err error) {
    ...

    for _, opt := range opts {
		opt.apply(&cc.dopts)
	}
    ...

    if !cc.dopts.insecure {
		if cc.dopts.copts.TransportCredentials == nil {
			return nil, errNoTransportSecurity
		}
	} else {
		if cc.dopts.copts.TransportCredentials != nil {
			return nil, errCredentialsConflict
		}
		for _, cd := range cc.dopts.copts.PerRPCCredentials {
			if cd.RequireTransportSecurity() {
				return nil, errTransportCredentialsMissing
			}
		}
	}
	...

	creds := cc.dopts.copts.TransportCredentials
	if creds != nil && creds.Info().ServerName != "" {
		cc.authority = creds.Info().ServerName
	} else if cc.dopts.insecure && cc.dopts.authority != "" {
		cc.authority = cc.dopts.authority
	} else {
		// Use endpoint from "scheme://authority/endpoint" as the default
		// authority for ClientConn.
		cc.authority = cc.parsedTarget.Endpoint
	}
	...
}
```

## gRPC

接下来我们将正式开始编码，在 gRPC Client/Server 上实现 TLS 证书认证的支持 🤔

### TLS Server

```go
package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

...

const PORT = "9001"

func main() {
	c, err := credentials.NewServerTLSFromFile("../../conf/server.pem", "../../conf/server.key")
	if err != nil {
		log.Fatalf("credentials.NewServerTLSFromFile err: %v", err)
	}

	server := grpc.NewServer(grpc.Creds(c))
	pb.RegisterSearchServiceServer(server, &SearchService{})

	lis, err := net.Listen("tcp", ":"+PORT)
	if err != nil {
		log.Fatalf("net.Listen err: %v", err)
	}

	server.Serve(lis)
}
```

- credentials.NewServerTLSFromFile：根据服务端输入的证书文件和密钥构造 TLS 凭证

```go
func NewServerTLSFromFile(certFile, keyFile string) (TransportCredentials, error) {
	cert, err := tls.LoadX509KeyPair(certFile, keyFile)
	if err != nil {
		return nil, err
	}
	return NewTLS(&tls.Config{Certificates: []tls.Certificate{cert}}), nil
}
```

- grpc.Creds()：返回一个 ServerOption，用于设置服务器连接的凭据。用于 `grpc.NewServer(opt ...ServerOption)` 为 gRPC Server 设置连接选项

```go
func Creds(c credentials.TransportCredentials) ServerOption {
	return func(o *options) {
		o.creds = c
	}
}
```

经过以上两个简单步骤，gRPC Server 就建立起需证书认证的服务啦 🤔

### TLS Client

```go
package main

import (
	"context"
	"log"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

const PORT = "9001"

func main() {
	c, err := credentials.NewClientTLSFromFile("../../conf/server.pem", "go-grpc-example")
	if err != nil {
		log.Fatalf("credentials.NewClientTLSFromFile err: %v", err)
	}

	conn, err := grpc.Dial(":"+PORT, grpc.WithTransportCredentials(c))
	if err != nil {
		log.Fatalf("grpc.Dial err: %v", err)
	}
	defer conn.Close()

	client := pb.NewSearchServiceClient(conn)
	resp, err := client.Search(context.Background(), &pb.SearchRequest{
		Request: "gRPC",
	})
	if err != nil {
		log.Fatalf("client.Search err: %v", err)
	}

	log.Printf("resp: %s", resp.GetResponse())
}
```

- credentials.NewClientTLSFromFile()：根据客户端输入的证书文件和密钥构造 TLS 凭证。serverNameOverride 为服务名称

```go
func NewClientTLSFromFile(certFile, serverNameOverride string) (TransportCredentials, error) {
	b, err := ioutil.ReadFile(certFile)
	if err != nil {
		return nil, err
	}
	cp := x509.NewCertPool()
	if !cp.AppendCertsFromPEM(b) {
		return nil, fmt.Errorf("credentials: failed to append certificates")
	}
	return NewTLS(&tls.Config{ServerName: serverNameOverride, RootCAs: cp}), nil
}
```

- grpc.WithTransportCredentials()：返回一个配置连接的 DialOption 选项。用于 `grpc.Dial(target string, opts ...DialOption)` 设置连接选项

```go
func WithTransportCredentials(creds credentials.TransportCredentials) DialOption {
	return newFuncDialOption(func(o *dialOptions) {
		o.copts.TransportCredentials = creds
	})
}
```

## 验证

### 请求

重新启动 server.go 和执行 client.go，得到响应结果

```
$ go run client.go
2018/09/30 20:00:21 resp: gRPC Server
```

### 抓个包

![image](https://image.eddycjy.com/c8ad6edf1f7d084883b847b3eee29dd2.jpg)

成功。

## 总结

在本章节我们实现了 gRPC TLS Client/Servert，你以为大功告成了吗？我不 😤

## 问题

你仔细再看看，Client 是基于 Server 端的证书和服务名称来建立请求的。这样的话，你就需要将 Server 的证书通过各种手段给到 Client 端，否则是无法完成这项任务的

问题也就来了，你无法保证你的“各种手段”是安全的，毕竟现在的网络环境是很危险的，万一被...

我们将在下一章节解决这个问题，保证其可靠性 🙂

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

================================================
FILE: content/posts/go/grpc/2018-10-08-ca-tls.md
================================================
---

title:      "「连载五」基于 CA 的 TLS 证书认证"
date:       2018-10-08 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

在上一章节中，我们提出了一个问题。就是如何保证证书的可靠性和有效性？你如何确定你 Server、Client 的证书是对的呢？

## CA

为了保证证书的可靠性和有效性，在这里可引入 CA 颁发的根证书的概念。其遵守 X.509 标准

### 根证书

根证书（root certificate）是属于根证书颁发机构（CA）的公钥证书。我们可以通过验证 CA 的签名从而信任 CA ，任何人都可以得到 CA 的证书（含公钥），用以验证它所签发的证书（客户端、服务端）


它包含的文件如下：

- 公钥
- 密钥

### 生成 Key

```
openssl genrsa -out ca.key 2048
```

### 生成密钥

```
openssl req -new -x509 -days 7200 -key ca.key -out ca.pem
```

#### 填写信息

```
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:go-grpc-example
Email Address []:
```

### Server

#### 生成 CSR

```
openssl req -new -key server.key -out server.csr
```

##### 填写信息

```
Country Name (2 letter code) []:
State or Province Name (full name) []:
Locality Name (eg, city) []:
Organization Name (eg, company) []:
Organizational Unit Name (eg, section) []:
Common Name (eg, fully qualified host name) []:go-grpc-example
Email Address []:

Please enter the following 'extra' attributes
to be sent with your certificate request
A challenge password []:
```

CSR 是 Cerificate Signing Request 的英文缩写，为证书请求文件。主要作用是 CA 会利用 CSR 文件进行签名使得攻击者无法伪装或篡改原有证书

#### 基于 CA 签发

```
openssl x509 -req -sha256 -CA ca.pem -CAkey ca.key -CAcreateserial -days 3650 -in server.csr -out server.pem
```

### Client

### 生成 Key

```
openssl ecparam -genkey -name secp384r1 -out client.key
```

### 生成 CSR

```
openssl req -new -key client.key -out client.csr
```

#### 基于 CA 签发

```
openssl x509 -req -sha256 -CA ca.pem -CAkey ca.key -CAcreateserial -days 3650 -in client.csr -out client.pem
```

### 整理目录

至此我们生成了一堆文件，请按照以下目录结构存放：

```
$ tree conf 
conf
├── ca.key
├── ca.pem
├── ca.srl
├── client
│   ├── client.csr
│   ├── client.key
│   └── client.pem
└── server
    ├── server.csr
    ├── server.key
    └── server.pem
```

另外有一些文件是不应该出现在仓库内，应当保密或删除的。但为了真实演示所以保留着（敲黑板）

## gRPC

接下来将正式开始针对 gRPC 进行编码，改造上一章节的代码。目标是基于 CA 进行 TLS 认证 🤫

### Server

```
package main

import (
	"context"
	"log"
	"net"
	"crypto/tls"
	"crypto/x509"
	"io/ioutil"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

...

const PORT = "9001"

func main() {
	cert, err := tls.LoadX509KeyPair("../../conf/server/server.pem", "../../conf/server/server.key")
	if err != nil {
		log.Fatalf("tls.LoadX509KeyPair err: %v", err)
	}

	certPool := x509.NewCertPool()
	ca, err := ioutil.ReadFile("../../conf/ca.pem")
	if err != nil {
		log.Fatalf("ioutil.ReadFile err: %v", err)
	}

	if ok := certPool.AppendCertsFromPEM(ca); !ok {
		log.Fatalf("certPool.AppendCertsFromPEM err")
	}

	c := credentials.NewTLS(&tls.Config{
		Certificates: []tls.Certificate{cert},
		ClientAuth:   tls.RequireAndVerifyClientCert,
		ClientCAs:    certPool,
	})

	server := grpc.NewServer(grpc.Creds(c))
	pb.RegisterSearchServiceServer(server, &SearchService{})

	lis, err := net.Listen("tcp", ":"+PORT)
	if err != nil {
		log.Fatalf("net.Listen err: %v", err)
	}

	server.Serve(lis)
}
```

- tls.LoadX509KeyPair()：从证书相关文件中**读取**和**解析**信息，得到证书公钥、密钥对

```
func LoadX509KeyPair(certFile, keyFile string) (Certificate, error) {
	certPEMBlock, err := ioutil.ReadFile(certFile)
	if err != nil {
		return Certificate{}, err
	}
	keyPEMBlock, err := ioutil.ReadFile(keyFile)
	if err != nil {
		return Certificate{}, err
	}
	return X509KeyPair(certPEMBlock, keyPEMBlock)
}
```

- x509.NewCertPool()：创建一个新的、空的 CertPool
- certPool.AppendCertsFromPEM()：尝试解析所传入的 PEM 编码的证书。如果解析成功会将其加到 CertPool 中，便于后面的使用
- credentials.NewTLS：构建基于 TLS 的 TransportCredentials 选项
- tls.Config：Config 结构用于配置 TLS 客户端或服务器

在 Server，共使用了三个 Config 配置项：

（1）Certificates：设置证书链，允许包含一个或多个

（2）ClientAuth：要求必须校验客户端的证书。可以根据实际情况选用以下参数：

```
const (
	NoClientCert ClientAuthType = iota
	RequestClientCert
	RequireAnyClientCert
	VerifyClientCertIfGiven
	RequireAndVerifyClientCert
)
```

（3）ClientCAs：设置根证书的集合，校验方式使用 ClientAuth 中设定的模式

### Client

```
package main

import (
	"context"
	"crypto/tls"
	"crypto/x509"
	"io/ioutil"
	"log"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

const PORT = "9001"

func main() {
	cert, err := tls.LoadX509KeyPair("../../conf/client/client.pem", "../../conf/client/client.key")
	if err != nil {
		log.Fatalf("tls.LoadX509KeyPair err: %v", err)
	}

	certPool := x509.NewCertPool()
	ca, err := ioutil.ReadFile("../../conf/ca.pem")
	if err != nil {
		log.Fatalf("ioutil.ReadFile err: %v", err)
	}

	if ok := certPool.AppendCertsFromPEM(ca); !ok {
		log.Fatalf("certPool.AppendCertsFromPEM err")
	}

	c := credentials.NewTLS(&tls.Config{
		Certificates: []tls.Certificate{cert},
		ServerName:   "go-grpc-example",
		RootCAs:      certPool,
	})

	conn, err := grpc.Dial(":"+PORT, grpc.WithTransportCredentials(c))
	if err != nil {
		log.Fatalf("grpc.Dial err: %v", err)
	}
	defer conn.Close()

	client := pb.NewSearchServiceClient(conn)
	resp, err := client.Search(context.Background(), &pb.SearchRequest{
		Request: "gRPC",
	})
	if err != nil {
		log.Fatalf("client.Search err: %v", err)
	}

	log.Printf("resp: %s", resp.GetResponse())
}
```

在 Client 中绝大部分与 Server 一致，不同点的地方是，在 Client 请求 Server 端时，Client 端会使用根证书和 ServerName 去对 Server 端进行校验

简单流程大致如下：

1. Client 通过请求得到 Server 端的证书
2. 使用 CA 认证的根证书对 Server 端的证书进行可靠性、有效性等校验
3. 校验 ServerName 是否可用、有效

当然了，在设置了 `tls.RequireAndVerifyClientCert` 模式的情况下，Server 也会使用 CA 认证的根证书对 Client 端的证书进行可靠性、有效性等校验。也就是两边都会进行校验，极大的保证了安全性 👍

### 验证

重新启动 server.go 和执行 client.go，查看响应结果是否正常

## 总结

在本章节，我们使用 CA 颁发的根证书对客户端、服务端的证书进行了签发。进一步的提高了两者的通讯安全 

这回是真的大功告成了！

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

================================================
FILE: content/posts/go/grpc/2018-10-10-interceptor.md
================================================
---

title:      "「连载六」Unary and Stream interceptor"
date:       2018-10-10 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

我想在每个 RPC 方法的前或后做某些事情，怎么做？

本章节将要介绍的拦截器（interceptor），就能帮你在合适的地方实现这些功能。

## 有几种方法

在 gRPC 中，大类可分为两种 RPC 方法，与拦截器的对应关系是：

- 普通方法：一元拦截器（grpc.UnaryInterceptor）
- 流方法：流拦截器（grpc.StreamInterceptor）


## 看一看

### grpc.UnaryInterceptor

```
func UnaryInterceptor(i UnaryServerInterceptor) ServerOption {
	return func(o *options) {
		if o.unaryInt != nil {
			panic("The unary server interceptor was already set and may not be reset.")
		}
		o.unaryInt = i
	}
}
```
函数原型：
```
type UnaryServerInterceptor func(ctx context.Context, req interface{}, info *UnaryServerInfo, handler UnaryHandler) (resp interface{}, err error)
```

通过查看源码可得知，要完成一个拦截器需要实现 `UnaryServerInterceptor` 方法。形参如下：

- ctx context.Context：请求上下文
- req interface{}：RPC 方法的请求参数
- info *UnaryServerInfo：RPC 方法的所有信息
- handler UnaryHandler：RPC 方法本身

### grpc.StreamInterceptor

```
func StreamInterceptor(i StreamServerInterceptor) ServerOption
```
函数原型：
```
type StreamServerInterceptor func(srv interface{}, ss ServerStream, info *StreamServerInfo, handler StreamHandler) error
```

StreamServerInterceptor 与 UnaryServerInterceptor 形参的意义是一样，不再赘述

### 如何实现多个拦截器

另外，可以发现 gRPC 本身居然只能设置一个拦截器，难道所有的逻辑都只能写在一起？

关于这一点，你可以放心。采用开源项目 [go-grpc-middleware](https://github.com/grpc-ecosystem/go-grpc-middleware) 就可以解决这个问题，本章也会使用它。

```
import "github.com/grpc-ecosystem/go-grpc-middleware"

myServer := grpc.NewServer(
    grpc.StreamInterceptor(grpc_middleware.ChainStreamServer(
        ...
    )),
    grpc.UnaryInterceptor(grpc_middleware.ChainUnaryServer(
       ...
    )),
)
```

## gRPC

从本节开始编写 gRPC interceptor 的代码，我们会将实现以下拦截器：

- logging：RPC 方法的入参出参的日志输出
- recover：RPC 方法的异常保护和日志输出

### 实现 interceptor

#### logging

```
func LoggingInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (interface{}, error) {
	log.Printf("gRPC method: %s, %v", info.FullMethod, req)
	resp, err := handler(ctx, req)
	log.Printf("gRPC method: %s, %v", info.FullMethod, resp)
	return resp, err
}
```

#### recover

```
func RecoveryInterceptor(ctx context.Context, req interface{}, info *grpc.UnaryServerInfo, handler grpc.UnaryHandler) (resp interface{}, err error) {
	defer func() {
		if e := recover(); e != nil {
			debug.PrintStack()
			err = status.Errorf(codes.Internal, "Panic err: %v", e)
		}
	}()

	return handler(ctx, req)
}
```

### Server

```
import (
	"context"
	"crypto/tls"
	"crypto/x509"
	"errors"
	"io/ioutil"
	"log"
	"net"
	"runtime/debug"

	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"
	"google.golang.org/grpc/status"
	"google.golang.org/grpc/codes"
	"github.com/grpc-ecosystem/go-grpc-middleware"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

...

func main() {
	c, err := GetTLSCredentialsByCA()
	if err != nil {
		log.Fatalf("GetTLSCredentialsByCA err: %v", err)
	}

	opts := []grpc.ServerOption{
		grpc.Creds(c),
		grpc_middleware.WithUnaryServerChain(
			RecoveryInterceptor,
			LoggingInterceptor,
		),
	}

	server := grpc.NewServer(opts...)
	pb.RegisterSearchServiceServer(server, &SearchService{})

	lis, err := net.Listen("tcp", ":"+PORT)
	if err != nil {
		log.Fatalf("net.Listen err: %v", err)
	}

	server.Serve(lis)
}
```

## 验证

### logging

启动 simple_server/server.go，执行 simple_client/client.go 发起请求，得到结果：

```
$ go run server.go
2018/10/02 13:46:35 gRPC method: /proto.SearchService/Search, request:"gRPC" 
2018/10/02 13:46:35 gRPC method: /proto.SearchService/Search, response:"gRPC Server"
```

### recover

在 RPC 方法中人为地制造运行时错误，再重复启动 server/client.go，得到结果：

#### client

```
$ go run client.go
2018/10/02 13:19:03 client.Search err: rpc error: code = Internal desc = Panic err: assignment to entry in nil map
exit status 1
```

#### server

```
$ go run server.go
goroutine 23 [running]:
runtime/debug.Stack(0xc420223588, 0x1033da9, 0xc420001980)
	/usr/local/Cellar/go/1.10.1/libexec/src/runtime/debug/stack.go:24 +0xa7
runtime/debug.PrintStack()
	/usr/local/Cellar/go/1.10.1/libexec/src/runtime/debug/stack.go:16 +0x22
main.RecoveryInterceptor.func1(0xc420223a10)
...
```

检查服务是否仍然运行，即可知道 Recovery 是否成功生效

## 总结

通过本章节，你可以学会最常见的拦截器使用方法。接下来其它“新”需求只要举一反三即可。

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

================================================
FILE: content/posts/go/grpc/2018-10-12-grpc-http.md
================================================
---

title:      "「连载七」让你的服务同时提供 HTTP 接口"
date:       2018-10-12 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

- 接口需要提供给其他业务组访问，但是 RPC 协议不同无法内调，对方问能否走 HTTP 接口，怎么办？

- 微信（公众号、小程序）等第三方回调接口只支持 HTTP 接口，怎么办

我相信你在实际工作中都会遇到如上问题，在 gRPC 中都是有解决方案的，本章节将会进行介绍 🤔 

## 为什么可以同时提供 HTTP 接口

关键一点，gRPC 的协议是基于 HTTP/2 的，因此应用程序能够在单个 TCP 端口上提供 HTTP/1.1 和 gRPC 接口服务（两种不同的流量）

## 怎么同时提供 HTTP 接口

### 检测协议

```
if r.ProtoMajor == 2 && strings.Contains(r.Header.Get("Content-Type"), "application/grpc") {
    server.ServeHTTP(w, r)
} else {
    mux.ServeHTTP(w, r)
}
```

### 流程

1. 检测请求协议是否为 HTTP/2
2. 判断 Content-Type 是否为 application/grpc（gRPC 的默认标识位）
3. 根据协议的不同转发到不同的服务处理

## gRPC

### TLS

在前面的章节，为了便于展示因此没有简单封装

在本节需复用代码，重新封装了，可详见：[go-grpc-example](https://github.com/EDDYCJY/go-grpc-example/tree/master/pkg/gtls)

### 目录结构

新建 simple_http_client、simple_http_server 目录，目录结构如下：

```
go-grpc-example
├── client
│   ├── simple_client
│   ├── simple_http_client
│   └── stream_client
├── conf
├── pkg
│   └── gtls
├── proto
├── server
│   ├── simple_http_server
│   ├── simple_server
│   └── stream_server
```

### Server

在 simple_http_server 目录下新建 server.go，写入文件内容：

```
package main

import (
	"context"
	"log"
	"net/http"
	"strings"

	"github.com/EDDYCJY/go-grpc-example/pkg/gtls"
	pb "github.com/EDDYCJY/go-grpc-example/proto"

	"google.golang.org/grpc"
)

type SearchService struct{}

func (s *SearchService) Search(ctx context.Context, r *pb.SearchRequest) (*pb.SearchResponse, error) {
	return &pb.SearchResponse{Response: r.GetRequest() + " HTTP Server"}, nil
}

const PORT = "9003"

func main() {
	certFile := "../../conf/server/server.pem"
	keyFile := "../../conf/server/server.key"
	tlsServer := gtls.Server{
		CertFile: certFile,
		KeyFile:  keyFile,
	}

	c, err := tlsServer.GetTLSCredentials()
	if err != nil {
		log.Fatalf("tlsServer.GetTLSCredentials err: %v", err)
	}

	mux := GetHTTPServeMux()

	server := grpc.NewServer(grpc.Creds(c))
	pb.RegisterSearchServiceServer(server, &SearchService{})

	http.ListenAndServeTLS(":"+PORT,
		certFile,
		keyFile,
		http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
			if r.ProtoMajor == 2 && strings.Contains(r.Header.Get("Content-Type"), "application/grpc") {
				server.ServeHTTP(w, r)
			} else {
				mux.ServeHTTP(w, r)
			}

			return
		}),
	)
}

func GetHTTPServeMux() *http.ServeMux {
	mux := http.NewServeMux()
	mux.HandleFunc("/", func(w http.ResponseWriter, r *http.Request) {
		w.Write([]byte("eddycjy: go-grpc-example"))
	})

	return mux
}
```

- http.NewServeMux：创建一个新的 ServeMux，ServeMux 本质上是一个路由表。它默认实现了 ServeHTTP，因此返回 Handler 后可直接通过 HandleFunc 注册 pattern 和处理逻辑的方法
- http.ListenAndServeTLS：可简单的理解为提供监听 HTTPS 服务的方法，重点的协议判断转发，也在这里面

其实，你理解后就会觉得很简单，核心步骤：判断 -> 转发 -> 响应。我们改变了前两步的默认逻辑，仅此而已

### Client

在 simple_http_server 目录下新建 client.go，写入文件内容：

```
package main

import (
	"context"
	"log"

	"google.golang.org/grpc"

	"github.com/EDDYCJY/go-grpc-example/pkg/gtls"
	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

const PORT = "9003"

func main() {
	tlsClient := gtls.Client{
		ServerName: "go-grpc-example",
		CertFile:   "../../conf/server/server.pem",
	}
	c, err := tlsClient.GetTLSCredentials()
	if err != nil {
		log.Fatalf("tlsClient.GetTLSCredentials err: %v", err)
	}

	conn, err := grpc.Dial(":"+PORT, grpc.WithTransportCredentials(c))
	if err != nil {
		log.Fatalf("grpc.Dial err: %v", err)
	}
	defer conn.Close()

	client := pb.NewSearchServiceClient(conn)
	resp, err := client.Search(context.Background(), &pb.SearchRequest{
		Request: "gRPC",
	})
	if err != nil {
		log.Fatalf("client.Search err: %v", err)
	}

	log.Printf("resp: %s", resp.GetResponse())
}
```

## 验证

### gRPC Client

```
$ go run client.go 
2018/10/04 14:56:56 resp: gRPC HTTP Server
```

### HTTP/1.1 访问

![image](https://image.eddycjy.com/1d92cb9e949e32eef7f8a64a6a77deb9.jpg)

## 总结

通过本章节，表面上完成了同端口提供双服务的功能，但实际上，应该是加深了 HTTP/2 的理解和使用，这才是本质

## 拓展

如果你有一个需求，是要**同时提供** RPC 和 RESTful JSON API 两种接口的，不要犹豫，点进去：[gRPC + gRPC Gateway 实践](https://segmentfault.com/a/1190000013339403)

## 问题

你以为这个方案就万能了吗，不。Envoy Proxy 的支持就不完美，无法同时监听一个端口的两种流量 😤

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

================================================
FILE: content/posts/go/grpc/2018-10-14-per-rpc-credentials.md
================================================
---

title:      "「连载八」对 RPC 方法做自定义认证"
date:       2018-10-14 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

在前面的章节中，我们介绍了两种（证书算一种）可全局认证的方法：

1. [TLS 证书认证](https://github.com/EDDYCJY/blog/blob/master/grpc/grpc-tls.md)
2. [基于 CA 的 TLS 证书认证](https://github.com/EDDYCJY/blog/blob/master/grpc/ca-tls.md)
3. [Unary and Stream interceptor](https://github.com/EDDYCJY/blog/blob/master/grpc/interceptor.md)


而在实际需求中，常常会对某些模块的 RPC 方法做特殊认证或校验。今天将会讲解、实现这块的功能点

## 课前知识

```
type PerRPCCredentials interface {
    GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error)
    RequireTransportSecurity() bool
}
```

在 gRPC 中默认定义了 PerRPCCredentials，它就是本章节的主角，是 gRPC 默认提供用于自定义认证的接口，它的作用是将所需的安全认证信息添加到每个 RPC 方法的上下文中。其包含 2 个方法：

- GetRequestMetadata：获取当前请求认证所需的元数据（metadata）
- RequireTransportSecurity：是否需要基于 TLS 认证进行安全传输

## 目录结构

新建 simple_token_server/server.go 和 simple_token_client/client.go，目录结构如下：

```
go-grpc-example
├── client
│   ├── simple_client
│   ├── simple_http_client
│   ├── simple_token_client
│   └── stream_client
├── conf
├── pkg
├── proto
├── server
│   ├── simple_http_server
│   ├── simple_server
│   ├── simple_token_server
│   └── stream_server
└── vendor
```

## gRPC

### Client

```
package main

import (
	"context"
	"log"

	"google.golang.org/grpc"

	"github.com/EDDYCJY/go-grpc-example/pkg/gtls"
	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

const PORT = "9004"

type Auth struct {
	AppKey    string
	AppSecret string
}

func (a *Auth) GetRequestMetadata(ctx context.Context, uri ...string) (map[string]string, error) {
	return map[string]string{"app_key": a.AppKey, "app_secret": a.AppSecret}, nil
}

func (a *Auth) RequireTransportSecurity() bool {
	return true
}

func main() {
	tlsClient := gtls.Client{
		ServerName: "go-grpc-example",
		CertFile:   "../../conf/server/server.pem",
	}
	c, err := tlsClient.GetTLSCredentials()
	if err != nil {
		log.Fatalf("tlsClient.GetTLSCredentials err: %v", err)
	}

	auth := Auth{
		AppKey:    "eddycjy",
		AppSecret: "20181005",
	}
	conn, err := grpc.Dial(":"+PORT, grpc.WithTransportCredentials(c), grpc.WithPerRPCCredentials(&auth))
	...
}
```

在 Client 端，重点实现 `type PerRPCCredentials interface` 所需的方法，关注两点即可：

- struct Auth：GetRequestMetadata、RequireTransportSecurity
- grpc.WithPerRPCCredentials

### Server

```
package main

import (
	"context"
	"log"
	"net"

	"google.golang.org/grpc"
	"google.golang.org/grpc/codes"
	"google.golang.org/grpc/metadata"
	"google.golang.org/grpc/status"

	"github.com/EDDYCJY/go-grpc-example/pkg/gtls"
	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

type SearchService struct {
	auth *Auth
}

func (s *SearchService) Search(ctx context.Context, r *pb.SearchRequest) (*pb.SearchResponse, error) {
	if err := s.auth.Check(ctx); err != nil {
		return nil, err
	}
	return &pb.SearchResponse{Response: r.GetRequest() + " Token Server"}, nil
}

const PORT = "9004"

func main() {
	...
}

type Auth struct {
	appKey    string
	appSecret string
}

func (a *Auth) Check(ctx context.Context) error {
	md, ok := metadata.FromIncomingContext(ctx)
	if !ok {
		return status.Errorf(codes.Unauthenticated, "自定义认证 Token 失败")
	}

	var (
		appKey    string
		appSecret string
	)
	if value, ok := md["app_key"]; ok {
		appKey = value[0]
	}
	if value, ok := md["app_secret"]; ok {
		appSecret = value[0]
	}

	if appKey != a.GetAppKey() || appSecret != a.GetAppSecret() {
		return status.Errorf(codes.Unauthenticated, "自定义认证 Token 无效")
	}

	return nil
}

func (a *Auth) GetAppKey() string {
	return "eddycjy"
}

func (a *Auth) GetAppSecret() string {
	return "20181005"
}
```

在 Server 端就更简单了，实际就是调用 `metadata.FromIncomingContext` 从上下文中获取 metadata，再在不同的 RPC 方法中进行认证检查

### 验证

重新启动 server.go 和 client.go，得到以下结果：

```
$ go run client.go
2018/10/05 20:59:58 resp: gRPC Token Server
```

修改 client.go 的值，制造两者不一致，得到无效结果：

```
$ go run client.go
2018/10/05 21:00:05 client.Search err: rpc error: code = Unauthenticated desc = invalid token
exit status 1
```

### 一个个加太麻烦

我相信你肯定会问一个个加，也太麻烦了吧？有这个想法的你，应当把 `type PerRPCCredentials interface` 做成一个拦截器（interceptor）

## 总结

本章节比较简单，主要是针对 RPC 方法的自定义认证进行了介绍，如果是想做全局的，建议是举一反三从拦截器下手哦。

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)


================================================
FILE: content/posts/go/grpc/2018-10-16-deadlines.md
================================================
---

title:      "「连载九」gRPC Deadlines"
date:       2018-10-16 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

## 前言

在前面的章节中，已经介绍了 gRPC 的基本用法。那你想想，让它这么裸跑真的没问题吗？

那么，肯定是有问题了。今天将介绍 gRPC Deadlines 的用法，这一个必备技巧。内容也比较简单

## Deadlines

Deadlines 意指截止时间，在 gRPC 中强调 TL;DR（Too long, Don't read）并建议**始终设定截止日期**，为什么呢？

### 为什么要设置

当未设置 Deadlines 时，将采用默认的 DEADLINE_EXCEEDED（这个时间非常大）

如果产生了阻塞等待，就会造成大量正在进行的请求都会被保留，并且所有请求都有可能达到最大超时

这会使服务面临资源耗尽的风险，例如内存，这会增加服务的延迟，或者在最坏的情况下可能导致整个进程崩溃

## gRPC

### Client

```
func main() {
    ...
	ctx, cancel := context.WithDeadline(context.Background(), time.Now().Add(time.Duration(5 * time.Second)))
	defer cancel()

	client := pb.NewSearchServiceClient(conn)
	resp, err := client.Search(ctx, &pb.SearchRequest{
		Request: "gRPC",
	})
	if err != nil {
		statusErr, ok := status.FromError(err)
		if ok {
			if statusErr.Code() == codes.DeadlineExceeded {
				log.Fatalln("client.Search err: deadline")
			}
		}

		log.Fatalf("client.Search err: %v", err)
	}

	log.Printf("resp: %s", resp.GetResponse())
}
```

- context.WithDeadline：会返回最终上下文截止时间。第一个形参为父上下文，第二个形参为调整的截止时间。若父级时间早于子级时间，则以父级时间为准，否则以子级时间为最终截止时间

```
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc) {
	if cur, ok := parent.Deadline(); ok && cur.Before(d) {
		// The current deadline is already sooner than the new one.
		return WithCancel(parent)
	}
	c := &timerCtx{
		cancelCtx: newCancelCtx(parent),
		deadline:  d,
	}
	propagateCancel(parent, c)
	dur := time.Until(d)
	if dur <= 0 {
		c.cancel(true, DeadlineExceeded) // deadline has already passed
		return c, func() { c.cancel(true, Canceled) }
	}
	c.mu.Lock()
	defer c.mu.Unlock()
	if c.err == nil {
		c.timer = time.AfterFunc(dur, func() {
			c.cancel(true, DeadlineExceeded)
		})
	}
	return c, func() { c.cancel(true, Canceled) }
}
```

- context.WithTimeout：很常见的另外一个方法，是便捷操作。实际上是对于 WithDeadline 的封装

```
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc) {
	return WithDeadline(parent, time.Now().Add(timeout))
}
```

- status.FromError：返回 GRPCStatus 的具体错误码，若为非法，则直接返回 `codes.Unknown`

### Server

```
type SearchService struct{}

func (s *SearchService) Search(ctx context.Context, r *pb.SearchRequest) (*pb.SearchResponse, error) {
	for i := 0; i < 5; i++  {
		if ctx.Err() == context.Canceled {
			return nil, status.Errorf(codes.Canceled, "SearchService.Search canceled")
		}

		time.Sleep(1 * time.Second)
	}

	return &pb.SearchResponse{Response: r.GetRequest() + " Server"}, nil
}

func main() {
	...
}
```

而在 Server 端，由于 Client 已经设置了截止时间。Server 势必要去检测它

否则如果 Client 已经结束掉了，Server 还傻傻的在那执行，这对资源是一种极大的浪费

因此在这里需要用 `ctx.Err() == context.Canceled` 进行判断，为了模拟场景我们加了循环和睡眠 🤔

### 验证

重新启动 server.go 和 client.go，得到结果：

```
$ go run client.go
2018/10/06 17:45:55 client.Search err: deadline
exit status 1
```

## 总结

本章节比较简单，你需要知道以下知识点：

- 怎么设置 Deadlines
- 为什么要设置 Deadlines

你要清楚地明白到，gRPC Deadlines 是很重要的，否则这小小的功能点就会要了你生产的命 🤫

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

### 资料

- [gRPC and Deadlines](https://grpc.io/blog/deadlines)


================================================
FILE: content/posts/go/grpc/2018-10-20-zipkin.md
================================================
---

title:      "「连载十」分布式链路追踪 gRPC + Opentracing + Zipkin"
date:       2018-10-20 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc
---

在实际应用中，你做了那么多 Server 端，写了 N 个 RPC 方法。想看看方法的指标，却无处下手？

本文将通过 gRPC + Opentracing + Zipkin 搭建一个**分布式链路追踪系统**来实现查看整个系统的链路、性能等指标。

## Opentracing

### 是什么

OpenTracing 通过提供平台无关、厂商无关的API，使得开发人员能够方便的添加（或更换）追踪系统的实现

不过 OpenTracing 并不是标准。因为 CNCF 不是官方标准机构，但是它的目标是致力为分布式追踪创建更标准的 API 和工具

### 名词解释

#### Trace

一个 trace 代表了一个事务或者流程在（分布式）系统中的执行过程

#### Span

一个 span 代表在分布式系统中完成的单个工作单元。也包含其他 span 的 “引用”，这允许将多个 spans 组合成一个完整的 Trace

每个 span 根据 OpenTracing 规范封装以下内容：

- 操作名称
- 开始时间和结束时间
- key:value span Tags
- key:value span Logs
- SpanContext

#### Tags

Span tags（跨度标签）可以理解为用户自定义的 Span 注释。便于查询、过滤和理解跟踪数据

#### Logs

Span logs（跨度日志）可以记录 Span 内特定时间或事件的日志信息。主要用于捕获特定 Span 的日志信息以及应用程序本身的其他调试或信息输出

#### SpanContext

SpanContext 代表跨越进程边界，传递到子级 Span 的状态。常在追踪示意图中创建上下文时使用

#### Baggage Items

Baggage Items 可以理解为 trace 全局运行中额外传输的数据集合

### 一个案例

![image](https://image.eddycjy.com/c7912244434f56f32be37ac66ad164ab.png)

图中可以看到以下内容：

- 执行时间的上下文
- 服务间的层次关系
- 服务间串行或并行调用链

结合以上信息，在实际场景中我们可以通过整个系统的调用链的上下文、性能等指标信息，一下子就能够发现系统的痛点在哪儿 

## Zipkin

![image](https://image.eddycjy.com/f82f883ce74801abfece12c775f45c6c.png)

### 是什么

Zipkin 是分布式追踪系统。它的作用是收集解决微服务架构中的延迟问题所需的时序数据。它管理这些数据的收集和查找

Zipkin 的设计基于 [Google Dapper](http://research.google.com/pubs/pub36356.html) 论文。

### 运行

```
docker run -d -p 9411:9411 openzipkin/zipkin
```

其他方法安装参见：https://github.com/openzipkin/zipkin

### 验证

访问 http://127.0.0.1:9411/zipkin/ 检查 Zipkin 是否运行正常

![image](https://image.eddycjy.com/f22ea6012f6ce4adea9f29d36f1017c7.jpg)

## gRPC + Opentracing + Zipkin

在前面的小节中，我们做了以下准备工作：

- 了解 Opentracing 是什么
- 搭建 Zipkin 提供分布式追踪系统的功能

接下来实现 gRPC 通过 Opentracing 标准 API 对接 Zipkin，再通过 Zipkin 去查看数据

### 目录结构

新建 simple_zipkin_client、simple_zipkin_server 目录，目录结构如下：

```
go-grpc-example
├── LICENSE
├── README.md
├── client
│   ├── ...
│   ├── simple_zipkin_client
├── conf
├── pkg
├── proto
├── server
│   ├── ...
│   ├── simple_zipkin_server
└── vendor
```

### 安装

```
$ go get -u github.com/openzipkin/zipkin-go-opentracing
$ go get -u github.com/grpc-ecosystem/grpc-opentracing/go/otgrpc
```

### gRPC

#### Server

```
package main

import (
	"context"
	"log"
	"net"

	"github.com/grpc-ecosystem/go-grpc-middleware"
	"github.com/grpc-ecosystem/grpc-opentracing/go/otgrpc"
	zipkin "github.com/openzipkin/zipkin-go-opentracing"
	"google.golang.org/grpc"

	"github.com/EDDYCJY/go-grpc-example/pkg/gtls"
	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

type SearchService struct{}

func (s *SearchService) Search(ctx context.Context, r *pb.SearchRequest) (*pb.SearchResponse, error) {
	return &pb.SearchResponse{Response: r.GetRequest() + " Server"}, nil
}

const (
	PORT = "9005"

	SERVICE_NAME              = "simple_zipkin_server"
	ZIPKIN_HTTP_ENDPOINT      = "http://127.0.0.1:9411/api/v1/spans"
	ZIPKIN_RECORDER_HOST_PORT = "127.0.0.1:9000"
)

func main() {
	collector, err := zipkin.NewHTTPCollector(ZIPKIN_HTTP_ENDPOINT)
	if err != nil {
		log.Fatalf("zipkin.NewHTTPCollector err: %v", err)
	}

	recorder := zipkin.NewRecorder(collector, true, ZIPKIN_RECORDER_HOST_PORT, SERVICE_NAME)

	tracer, err := zipkin.NewTracer(
		recorder, zipkin.ClientServerSameSpan(false),
	)
	if err != nil {
		log.Fatalf("zipkin.NewTracer err: %v", err)
	}

	tlsServer := gtls.Server{
		CaFile:   "../../conf/ca.pem",
		CertFile: "../../conf/server/server.pem",
		KeyFile:  "../../conf/server/server.key",
	}
	c, err := tlsServer.GetCredentialsByCA()
	if err != nil {
		log.Fatalf("GetTLSCredentialsByCA err: %v", err)
	}

	opts := []grpc.ServerOption{
		grpc.Creds(c),
		grpc_middleware.WithUnaryServerChain(
			otgrpc.OpenTracingServerInterceptor(tracer, otgrpc.LogPayloads()),
		),
	}
    ...
}
```

- zipkin.NewHTTPCollector：创建一个 Zipkin HTTP 后端收集器  
- zipkin.NewRecorder：创建一个基于 Zipkin 收集器的记录器
- zipkin.NewTracer：创建一个 OpenTracing 跟踪器（兼容 Zipkin Tracer）
- otgrpc.OpenTracingClientInterceptor：返回 grpc.UnaryServerInterceptor，不同点在于该拦截器会在 gRPC Metadata 中查找 OpenTracing SpanContext。如果找到则为该服务的 Span Context 的子节点 
- otgrpc.LogPayloads：设置并返回 Option。作用是让 OpenTracing 在双向方向上记录应用程序的有效载荷（payload）

总的来讲，就是初始化 Zipkin，其又包含收集器、记录器、跟踪器。再利用拦截器在 Server 端实现 SpanContext、Payload 的双向读取和管理

#### Client

```
func main() {
	// the same as zipkin server
	// ...
	conn, err := grpc.Dial(":"+PORT, grpc.WithTransportCredentials(c),
		grpc.WithUnaryInterceptor(
			otgrpc.OpenTracingClientInterceptor(tracer, otgrpc.LogPayloads()),
		))
	...
}
```

- otgrpc.OpenTracingClientInterceptor：返回 grpc.UnaryClientInterceptor。该拦截器的核心功能在于：

（1）OpenTracing SpanContext 注入 gRPC Metadata 

（2）查看 context.Context 中的上下文关系，若存在父级 Span 则创建一个 ChildOf 引用，得到一个子 Span

其他方面，与 Server 端是一致的，先初始化 Zipkin，再增加 Client 端特需的拦截器。就可以完成基础工作啦

### 验证

启动 Server.go，执行 Client.go。查看 http://127.0.0.1:9411/zipkin/ 的示意图：

![image](https://image.eddycjy.com/35c586cc15b28496d5c227e03cde7e67.jpg)

![image](https://image.eddycjy.com/8c17c36d87764237e75b4d7c4739fdf4.jpg)

## 复杂点

![image](https://image.eddycjy.com/d33c339e872ceab76c906e2da1a450c3.jpg)

![image](https://image.eddycjy.com/dc3fc3ec49276d3b56c0c2d22e6a5ad4.jpg)

来，自己实践一下

## 总结

在多服务下的架构下，串行、并行、服务套服务是一个非常常见的情况，用常规的方案往往很难发现问题在哪里（成本太大）。而这种情况就是**分布式追踪系统**大展拳脚的机会了

希望你通过本章节的介绍和学习，能够了解其概念和搭建且应用一个追踪系统。

## 参考

### 本系列示例代码

- [go-grpc-example](https://github.com/EDDYCJY/go-grpc-example)

### 资料

- [opentracing](https://opentracing.io/)
- [zipkin](https://zipkin.io)



================================================
FILE: content/posts/go/grpc-gateway/2018-02-23-install.md
================================================
---

title:      "「连载一」gRPC介绍与环境安装"
date:       2018-02-23 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc-gateway
---

假定我们有一个项目需求，希望用`Rpc`作为内部`API`的通讯，同时也想对外提供`Restful Api`，写两套又太繁琐不符合

于是我们想到了`Grpc`以及`Grpc Gateway`，这就是我们所需要的

![image](https://camo.githubusercontent.com/e75a8b46b078a3c1df0ed9966a16c24add9ccb83/68747470733a2f2f646f63732e676f6f676c652e636f6d2f64726177696e67732f642f3132687034435071724e5046686174744c5f63496f4a707446766c41716d35774c513067677149356d6b43672f7075623f773d37343926683d333730)

## 准备环节
在正式开始我们的`Grpc`+`Grpc Gateway`实践前，我们需要先配置好我们的开发环境
- Grpc
- Protoc Plugin
- Protocol Buffers
- Grpc-gateway

## Grpc

### 是什么
Google对`Grpc`的定义：
> A high performance, open-source universal RPC framework

也就是`Grpc`是一个高性能、开源的通用RPC框架，具有以下特性：
- 强大的`IDL`，使用`Protocol Buffers`作为数据交换的格式，支持`v2`、`v3`（推荐`v3`）
- 跨语言、跨平台，也就是`Grpc`支持多种平台和语言
- **支持HTTP2**，双向传输、多路复用、认证等


### 安装
1、官方推荐（需科学上网）
```
go get -u google.golang.org/grpc
```
2、通过`github.com`


进入到第一个$GOPATH目录（因为`go get` 会默认安装在第一个下）下，新建`google.golang.org`目录，拉取`golang`在`github`上的镜像库：
```
cd /usr/local/go/path/src   

mkdir google.golang.org

cd google.golang.org/

git clone https://github.com/grpc/grpc-go

mv grpc-go/ grpc/
```

目录结构：
```
google.golang.org/
└── grpc
    ...
```

而在`grpc`下有许多常用的包，例如：
- [metadata](https://gowalker.org/google.golang.org/grpc/metadata)：定义了`grpc`所支持的元数据结构，包中方法可以对`MD`进行获取和处理
- [credentials](https://gowalker.org/google.golang.org/grpc/credentials)：实现了`grpc`所支持的各种认证凭据，封装了客户端对服务端进行身份验证所需要的所有状态，并做出各种断言
- [codes](https://gowalker.org/google.golang.org/grpc/codes)：定义了`grpc`使用的标准错误码，可通用

## Protoc Plugin

### 是什么
编译器插件

### 安装
```
go get -u github.com/golang/protobuf/protoc-gen-go
```
将`Protoc Plugin`的可执行文件从$GOPATH中移动到$GOBIN下
```
mv /usr/local/go/path/bin/protoc-gen-go /usr/local/go/bin/
```

## Protocol Buffers v3
### 是什么
>Protocol buffers are a flexible, efficient, automated mechanism for serializing structured data – think XML, but smaller, faster, and simpler. You define how you want your data to be structured once, then you can use special generated source code to easily write and read your structured data to and from a variety of data streams and using a variety of languages. You can even update your data structure without breaking deployed programs that are compiled against the "old" format.

`Protocol Buffers`是`Google`推出的一种数据描述语言，支持多语言、多平台，它是一种二进制的格式，总得来说就是更小、更快、更简单、更灵活，目前分别有`v2`、`v3`的版本，我们推荐使用`v3`

- [proto2 文档地址](https://developers.google.com/protocol-buffers/docs/proto)
- [proto3 文档地址](https://developers.google.com/protocol-buffers/docs/proto3)

建议可以阅读下官方文档的介绍，本系列会在使用时简单介绍所涉及的内容

### 安装

```
wget https://github.com/google/protobuf/releases/download/v3.5.1/protobuf-all-3.5.1.zip
unzip protobuf-all-3.5.1.zip
cd protobuf-3.5.1/
./configure
make
make install
```

检查是否安装成功
```
protoc --version
```

如果出现报错
```
protoc: error while loading shared libraries: libprotobuf.so.15: cannot open shared object file: No such file or directory
```
则执行`ldconfig`后，再次运行即可成功

#### 为什么要执行`ldconfig`
我们通过控制台输出的信息可以知道，`Protocol Buffers Libraries`的默认安装路径在`/usr/local/lib`

```
Libraries have been installed in:
   /usr/local/lib

If you ever happen to want to link against installed libraries
in a given directory, LIBDIR, you must either use libtool, and
specify the full pathname of the library, or use the `-LLIBDIR'
flag during linking and do at least one of the following:
   - add LIBDIR to the `LD_LIBRARY_PATH' environment variable
     during execution
   - add LIBDIR to the `LD_RUN_PATH' environment variable
     during linking
   - use the `-Wl,-rpath -Wl,LIBDIR' linker flag
   - have your system administrator add LIBDIR to `/etc/ld.so.conf'

See any operating system documentation about shared libraries for
more information, such as the ld(1) and ld.so(8) manual pages.
```

而我们安装了一个新的动态链接库，`ldconfig`一般在系统启动时运行，所以现在会找不到这个`lib`，因此我们要手动执行`ldconfig`，**让动态链接库为系统所共享，它是一个动态链接库管理命令**，这就是`ldconfig`命令的作用

### protoc使用
我们按照惯例执行`protoc --help`（查看帮助文档），我们抽出几个常用的命令进行讲解

1、`-IPATH, --proto_path=PATH`：指定`import`搜索的目录，可指定多个，如果不指定则默认当前工作目录

2、`--go_out`：生成`golang`源文件

#### 参数
若要将额外的参数传递给插件，可使用从输出目录中分离出来的逗号分隔的参数列表:
```
protoc --go_out=plugins=grpc,import_path=mypackage:. *.proto
```

- `import_prefix=xxx`：将指定前缀添加到所有`import`路径的开头
- `import_path=foo/bar`：如果文件没有声明`go_package`，则用作包。如果它包含斜杠，那么最右边的斜杠将被忽略。
- `plugins=plugin1+plugin2`：指定要加载的子插件列表（我们所下载的repo中唯一的插件是grpc）
- `Mfoo/bar.proto=quux/shme`： `M`参数，指定`.proto`文件编译后的包名（`foo/bar.proto`编译后为包名为`quux/shme`）

#### Grpc支持
如果`proto`文件指定了`RPC`服务，`protoc-gen-go`可以生成与`grpc`相兼容的代码，我们仅需要将`plugins=grpc`参数传递给`--go_out`，就可以达到这个目的
```
protoc --go_out=plugins=grpc:. *.proto
```

## Grpc-gateway

### 是什么
> grpc-gateway is a plugin of protoc. It reads gRPC service definition, and generates a reverse-proxy server which translates a RESTful JSON API into gRPC. This server is generated according to custom options in your gRPC definition.

[grpc-gateway](https://github.com/grpc-ecosystem/grpc-gateway)是protoc的一个插件。它读取gRPC服务定义，并生成一个反向代理服务器，将RESTful JSON API转换为gRPC。此服务器是根据gRPC定义中的自定义选项生成的。

### 安装
```
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
```

如果出现以下报错，我们分析错误提示可得知是连接超时（大概是被墙了）
```
package google.golang.org/genproto/googleapis/api/annotations: unrecognized import path "google.golang.org/genproto/googleapis/api/annotations" (https fetch: Get https://google.golang.org/genproto/googleapis/api/annotations?go-get=1: dial tcp 216.239.37.1:443: getsockopt: connection timed out)
```

有两种解决方法，

1、科学上网

2、通过`github.com`

进入到第一个$GOTPATH目录的`google.golang.org`目录下，拉取`genproto`在`github`上的`go-genproto`镜像库：
```
cd /usr/local/go/path/src/google.golang.org

git clone https://github.com/google/go-genproto.git

mv go-genproto/ genproto/
```


在安装完毕后，我们将`grpc-gateway`的可执行文件从$GOPATH中移动到$GOBIN
```
mv /usr/local/go/path/bin/protoc-gen-grpc-gateway /usr/local/go/bin/
```

到这里我们这节就基本完成了，建议多反复看几遍加深对各个组件的理解！

## 参考
### 示例代码
- [grpc-hello-world](https://github.com/EDDYCJY/grpc-hello-world)



================================================
FILE: content/posts/go/grpc-gateway/2018-02-27-hello-world.md
================================================
---

title:      "「连载二」Hello World"
date:       2018-02-27 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc-gateway
---

这节将开始编写一个复杂的Hello World，涉及到许多的知识，建议大家认真思考其中的概念

## 需求
由于本实践偏向`Grpc`+`Grpc Gateway`的方面，我们的需求是**同一个服务端支持`Rpc`和`Restful Api`**，那么就意味着`http2`、`TLS`等等的应用，功能方面就是一个服务端能够接受来自`grpc`和`Restful Api`的请求并响应

## 一、初始化目录

我们先在$GOPATH中新建`grpc-hello-world`文件夹，我们项目的初始目录目录如下：
```
grpc-hello-world/
├── certs
├── client
├── cmd
├── pkg
├── proto
│   ├── google
│   │   └── api
└── server
```
- `certs`：证书凭证
- `client`：客户端
- `cmd`：命令行
- `pkg`：第三方公共模块
- `proto`：`protobuf`的一些相关文件（含`.proto`、`pb.go`、`.pb.gw.go`)，`google/api`中用于存放`annotations.proto`、`http.proto`
- `server`：服务端

## 二、制作证书

在服务端支持`Rpc`和`Restful Api`，需要用到`TLS`，因此我们要先制作证书

进入`certs`目录，生成`TLS`所需的公钥密钥文件

### 私钥
```
openssl genrsa -out server.key 2048

openssl ecparam -genkey -name secp384r1 -out server.key
```
- `openssl genrsa`：生成`RSA`私钥，命令的最后一个参数，将指定生成密钥的位数，如果没有指定，默认512
- `openssl ecparam`：生成`ECC`私钥，命令为椭圆曲线密钥参数生成及操作，本文中`ECC`曲线选择的是`secp384r1`

### 自签名公钥
```
openssl req -new -x509 -sha256 -key server.key -out server.pem -days 3650
```
- `openssl req`：生成自签名证书，`-new`指生成证书请求、`-sha256`指使用`sha256`加密、`-key`指定私钥文件、`-x509`指输出证书、`-days 3650`为有效期，此后则输入证书拥有者信息

### 填写信息
```
Country Name (2 letter code) [XX]:
State or Province Name (full name) []:
Locality Name (eg, city) [Default City]:
Organization Name (eg, company) [Default Company Ltd]:
Organizational Unit Name (eg, section) []:
Common Name (eg, your name or your server's hostname) []:grpc server name
Email Address []:
```
## 三、`proto`
### 编写

1、 `google.api`

我们看到`proto`目录中有`google/api`目录，它用到了`google`官方提供的两个`api`描述文件，主要是针对`grpc-gateway`的`http`转换提供支持，定义了`Protocol Buffer`所扩展的`HTTP Option`

`annotations.proto`文件：
```
// Copyright (c) 2015, Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.api;

import "google/api/http.proto";
import "google/protobuf/descriptor.proto";

option java_multiple_files = true;
option java_outer_classname = "AnnotationsProto";
option java_package = "com.google.api";

extend google.protobuf.MethodOptions {
  // See `HttpRule`.
  HttpRule http = 72295728;
}

```

`http.proto`文件：
```
// Copyright 2016 Google Inc.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package google.api;

option cc_enable_arenas = true;
option java_multiple_files = true;
option java_outer_classname = "HttpProto";
option java_package = "com.google.api";


// Defines the HTTP configuration for a service. It contains a list of
// [HttpRule][google.api.HttpRule], each specifying the mapping of an RPC method
// to one or more HTTP REST API methods.
message Http {
  // A list of HTTP rules for configuring the HTTP REST API methods.
  repeated HttpRule rules = 1;
}

// Use CustomHttpPattern to specify any HTTP method that is not included in the
// `pattern` field, such as HEAD, or "*" to leave the HTTP method unspecified for
// a given URL path rule. The wild-card rule is useful for services that provide
// content to Web (HTML) clients.
message HttpRule {
  // Selects methods to which this rule applies.
  //
  // Refer to [selector][google.api.DocumentationRule.selector] for syntax details.
  string selector = 1;

  // Determines the URL pattern is matched by this rules. This pattern can be
  // used with any of the {get|put|post|delete|patch} methods. A custom method
  // can be defined using the 'custom' field.
  oneof pattern {
    // Used for listing and getting information about resources.
    string get = 2;

    // Used for updating a resource.
    string put = 3;

    // Used for creating a resource.
    string post = 4;

    // Used for deleting a resource.
    string delete = 5;

    // Used for updating a resource.
    string patch = 6;

    // Custom pattern is used for defining custom verbs.
    CustomHttpPattern custom = 8;
  }

  // The name of the request field whose value is mapped to the HTTP body, or
  // `*` for mapping all fields not captured by the path pattern to the HTTP
  // body. NOTE: the referred field must not be a repeated field.
  string body = 7;

  // Additional HTTP bindings for the selector. Nested bindings must
  // not contain an `additional_bindings` field themselves (that is,
  // the nesting may only be one level deep).
  repeated HttpRule additional_bindings = 11;
}

// A custom pattern is used for defining custom HTTP verb.
message CustomHttpPattern {
  // The name of this custom HTTP verb.
  string kind = 1;

  // The path matched by this custom verb.
  string path = 2;
}

```

2. `hello.proto`

这一小节将编写`Demo`的`.proto`文件，我们在`proto`目录下新建`hello.proto`文件，写入文件内容：
```
syntax = "proto3";

package proto;

import "google/api/annotations.proto";

service HelloWorld {
    rpc SayHelloWorld(HelloWorldRequest) returns (HelloWorldResponse) {
        option (google.api.http) = {
            post: "/hello_world"
            body: "*"
        };
    }
}

message HelloWorldRequest {
    string referer = 1;
}

message HelloWorldResponse {
    string message = 1;
}
```

在`hello.proto`文件中，引用了`google/api/annotations.proto`，达到支持`HTTP Option`的效果

- 定义了一个`service`RPC服务`HelloWorld`，在其内部定义了一个`HTTP Option`的`POST`方法，`HTTP`响应路径为`/hello_world`
- 定义`message`类型`HelloWorldRequest`、`HelloWorldResponse`，用于响应请求和返回结果

### 编译

在编写完`.proto`文件后，我们需要对其进行编译，就能够在`server`中使用

进入`proto`目录，执行以下命令

```
# 编译google.api
protoc -I . --go_out=plugins=grpc,Mgoogle/protobuf/descriptor.proto=github.com/golang/protobuf/protoc-gen-go/descriptor:. google/api/*.proto

#编译hello_http.proto为hello_http.pb.proto
protoc -I . --go_out=plugins=grpc,Mgoogle/api/annotations.proto=grpc-hello-world/proto/google/api:. ./hello.proto

#编译hello_http.proto为hello_http.pb.gw.proto
protoc --grpc-gateway_out=logtostderr=true:. ./hello.proto
```

执行完毕后将生成`hello.pb.go`和`hello.gw.pb.go`，分别针对`grpc`和`grpc-gateway`的功能支持


## 四、命令行模块 `cmd`
### 介绍
这一小节我们编写命令行模块，为什么要独立出来呢，是为了将`cmd`和`server`两者解耦，避免混淆在一起。

我们采用 [Cobra](https://github.com/spf13/cobra) 来完成这项功能，`Cobra`既是创建强大的现代CLI应用程序的库，也是生成应用程序和命令文件的程序。提供了以下功能：

- 简易的子命令行模式
- 完全兼容posix的命令行模式(包括短和长版本)
- 嵌套的子命令
- 全局、本地和级联`flags`
- 使用`Cobra`很容易的生成应用程序和命令，使用`cobra create appname`和`cobra add cmdname`
- 智能提示
- 自动生成commands和flags的帮助信息
- 自动生成详细的help信息`-h`，`--help`等等
- 自动生成的bash自动完成功能
- 为应用程序自动生成手册
- 命令别名
- 定义您自己的帮助、用法等的灵活性。
- 可选与[viper](https://github.com/spf13/viper)紧密集成的apps

### 编写`server`

在编写`cmd`时需要先用`server`进行测试关联，因此这一步我们先写`server.go`用于测试

在`server`模块下 新建`server.go`文件，写入测试内容：
```
package server

import (
    "log"
)

var (
    ServerPort string
    CertName string
    CertPemPath string
    CertKeyPath string
)

func Serve() (err error){
    log.Println(ServerPort)
    
    log.Println(CertName)
    
    log.Println(CertPemPath)
    
    log.Println(CertKeyPath)
    
    return nil
}

```
### 编写`cmd`

在`cmd`模块下 新建`root.go`文件，写入内容：
```
package cmd

import (
    "fmt"
    "os"

    "github.com/spf13/cobra"
)

var rootCmd = &cobra.Command{
    Use:   "grpc",
    Short: "Run the gRPC hello-world server",
}

func Execute() {
    if err := rootCmd.Execute(); err != nil {
        fmt.Println(err)
        os.Exit(-1)
    }
}
```
新建`server.go`文件，写入内容：
```
package cmd

import (
	"log"

	"github.com/spf13/cobra"
	
	"grpc-hello-world/server"
)

var serverCmd = &cobra.Command{
	Use:   "server",
	Short: "Run the gRPC hello-world server",
	Run: func(cmd *cobra.Command, args []string) {
		defer func() {
			if err := recover(); err != nil {
				log.Println("Recover error : %v", err)
			}
		}()
		
		server.Serve()
	},
}

func init() {
	serverCmd.Flags().StringVarP(&server.ServerPort, "port", "p", "50052", "server port")
	serverCmd.Flags().StringVarP(&server.CertPemPath, "cert-pem", "", "./certs/server.pem", "cert pem path")
	serverCmd.Flags().StringVarP(&server.CertKeyPath, "cert-key", "", "./certs/server.key", "cert key path")
	serverCmd.Flags().StringVarP(&server.CertName, "cert-name", "", "grpc server name", "server's hostname")
	rootCmd.AddCommand(serverCmd)
}
```

我们在`grpc-hello-world/`目录下，新建文件`main.go`，写入内容：
```
package main

import (
	"grpc-hello-world/cmd"
)

func main() {
	cmd.Execute()
}
```

### 讲解

要使用`Cobra`，按照`Cobra`标准要创建`main.go`和一个`rootCmd`文件，另外我们有子命令`server`

1、`rootCmd`：
`rootCmd`表示在没有任何子命令的情况下的基本命令

2、`&cobra.Command`：
- `Use`：`Command`的用法，`Use`是一个行用法消息
- `Short`：`Short`是`help`命令输出中显示的简短描述
- `Run`：运行:典型的实际工作功能。大多数命令只会实现这一点；另外还有`PreRun`、`PreRunE`、`PostRun`、`PostRunE`等等不同时期的运行命令，但比较少用，具体使用时再查看亦可

3、`rootCmd.AddCommand`：`AddCommand`向这父命令（`rootCmd`）添加一个或多个命令

4、`serverCmd.Flags().StringVarP()`：

一般来说，我们需要在`init()`函数中定义`flags`和处理配置，以`serverCmd.Flags().StringVarP(&server.ServerPort, "port", "p", "50052", "server port")`为例，我们定义了一个`flag`，值存储在`&server.ServerPort`中，长命令为`--port`，短命令为`-p`，，默认值为`50052`，命令的描述为`server port`。这一种调用方式成为`Local Flags`

我们延伸一下，如果觉得每一个子命令都要设一遍觉得很麻烦，我们可以采用`Persistent Flags`：

`rootCmd.PersistentFlags().BoolVarP(&Verbose, "verbose", "v", false, "verbose output")`

作用：

`flag`是可以持久的，这意味着该`flag`将被分配给它所分配的命令以及该命令下的每个命令。对于全局标记，将标记作为根上的持久标志。

另外还有`Local Flag on Parent Commands`、`Bind Flags with Config`、`Required flags`等等，使用到再 [传送](https://github.com/spf13/cobra#local-flag-on-parent-commands) 了解即可


### 测试
回到`grpc-hello-world/`目录下执行`go run main.go server`，查看输出是否为（此时应为默认值）：
```
2018/02/25 23:23:21 50052
2018/02/25 23:23:21 dev
2018/02/25 23:23:21 ./certs/server.pem
2018/02/25 23:23:21 ./certs/server.key
```

执行`go run main.go server --port=8000 --cert-pem=test-pem --cert-key=test-key --cert-name=test-name`，检验命令行参数是否正确：
```
2018/02/25 23:24:56 8000
2018/02/25 23:24:56 test-name
2018/02/25 23:24:56 test-pem
2018/02/25 23:24:56 test-key
```

若都无误，那么恭喜你`cmd`模块的编写正确了，下一部分开始我们的重点章节！

## 五、服务端模块 `server`


### 编写`hello.go`
在`server`目录下新建文件`hello.go`，写入文件内容：
```
package server

import (
	"golang.org/x/net/context"

	pb "grpc-hello-world/proto"
)

type helloService struct{}

func NewHelloService() *helloService {
	return &helloService{}
}

func (h helloService) SayHelloWorld(ctx context.Context, r *pb.HelloWorldRequest) (*pb.HelloWorldResponse, error) {
	return &pb.HelloWorldResponse{
		Message : "test",
	}, nil
}
```

我们创建了`helloService`及其方法`SayHelloWorld`，对应`.proto`的`rpc SayHelloWorld`，这个方法需要有2个参数：`ctx context.Context`用于接受上下文参数、`r *pb.HelloWorldRequest`用于接受`protobuf`的`Request`参数（对应`.proto`的`message HelloWorldRequest`）


### *编写`server.go`
这一小章节，我们编写最为重要的服务端程序部分，涉及到大量的`grpc`、`grpc-gateway`及一些网络知识的应用

1、在`pkg`下新建`util`目录，新建`grpc.go`文件，写入内容：
```
package util

import (
	"net/http"
	"strings"

	"google.golang.org/grpc"
)

func GrpcHandlerFunc(grpcServer *grpc.Server, otherHandler http.Handler) http.Handler {
    if otherHandler == nil {
        return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
            grpcServer.ServeHTTP(w, r)
        })
    }
    return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
        if r.ProtoMajor == 2 && strings.Contains(r.Header.Get("Content-Type"), "application/grpc") {
            grpcServer.ServeHTTP(w, r)
        } else {
            otherHandler.ServeHTTP(w, r)
        }
    })
}
```

`GrpcHandlerFunc`函数是用于判断请求是来源于`Rpc`客户端还是`Restful Api`的请求，根据不同的请求注册不同的`ServeHTTP`服务；`r.ProtoMajor == 2`也代表着请求必须基于`HTTP/2`

2、在`pkg`下的`util`目录下，新建`tls.go`文件，写入内容：
```
package util

import (
	"crypto/tls"
    "io/ioutil"
    "log"

    "golang.org/x/net/http2"
)

func GetTLSConfig(certPemPath, certKeyPath string) *tls.Config {
    var certKeyPair *tls.Certificate
    cert, _ := ioutil.ReadFile(certPemPath)
    key, _ := ioutil.ReadFile(certKeyPath)
    
    pair, err := tls.X509KeyPair(cert, key)
    if err != nil {
        log.Println("TLS KeyPair err: %v\n", err)
    }
    
    certKeyPair = &pair

    return &tls.Config{
        Certificates: []tls.Certificate{*certKeyPair},
        NextProtos:   []string{http2.NextProtoTLS},
    }
}
```

`GetTLSConfig`函数是用于获取`TLS`配置，在内部，我们读取了`server.key`和`server.pem`这类证书凭证文件
- `tls.X509KeyPair`：从一对`PEM`编码的数据中解析公钥/私钥对。成功则返回公钥/私钥对
- `http2.NextProtoTLS`：`NextProtoTLS`是谈判期间的`NPN/ALPN`协议，用于**HTTP/2的TLS设置**
- `tls.Certificate`：返回一个或多个证书，实质我们解析`PEM`调用的`X509KeyPair`的函数声明就是`func X509KeyPair(certPEMBlock, keyPEMBlock []byte) (Certificate, error)`，返回值就是`Certificate`

总的来说该函数是用于处理从证书凭证文件（PEM），最终获取`tls.Config`作为`HTTP2`的使用参数

3、修改`server`目录下的`server.go`文件，该文件是我们服务里的核心文件，写入内容：
```
package server

import (
    "crypto/tls"
    "net"
    "net/http"
    "log"

    "golang.org/x/net/context"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "github.com/grpc-ecosystem/grpc-gateway/runtime"
    
    pb "grpc-hello-world/proto"
    "grpc-hello-world/pkg/util"
)

var (
    ServerPort string
    CertName string
    CertPemPath string
    CertKeyPath string
    EndPoint string
)

func Serve() (err error){
    EndPoint = ":" + ServerPort
    conn, err := net.Listen("tcp", EndPoint)
    if err != nil {
        log.Printf("TCP Listen err:%v\n", err)
    }

    tlsConfig := util.GetTLSConfig(CertPemPath, CertKeyPath)
    srv := createInternalServer(conn, tlsConfig)

    log.Printf("gRPC and https listen on: %s\n", ServerPort)

    if err = srv.Serve(tls.NewListener(conn, tlsConfig)); err != nil {
        log.Printf("ListenAndServe: %v\n", err)
    }

    return err
}

func createInternalServer(conn net.Listener, tlsConfig *tls.Config) (*http.Server) {
    var opts []grpc.ServerOption

    // grpc server
    creds, err := credentials.NewServerTLSFromFile(CertPemPath, CertKeyPath)
    if err != nil {
        log.Printf("Failed to create server TLS credentials %v", err)
    }

    opts = append(opts, grpc.Creds(creds))
    grpcServer := grpc.NewServer(opts...)

    // register grpc pb
    pb.RegisterHelloWorldServer(grpcServer, NewHelloService())

    // gw server
    ctx := context.Background()
    dcreds, err := credentials.NewClientTLSFromFile(CertPemPath, CertName)
    if err != nil {
        log.Printf("Failed to create client TLS credentials %v", err)
    }
    dopts := []grpc.DialOption{grpc.WithTransportCredentials(dcreds)}
    gwmux := runtime.NewServeMux()

    // register grpc-gateway pb
    if err := pb.RegisterHelloWorldHandlerFromEndpoint(ctx, gwmux, EndPoint, dopts); err != nil {
        log.Printf("Failed to register gw server: %v\n", err)
    }

    // http服务
    mux := http.NewServeMux()
    mux.Handle("/", gwmux)

    return &http.Server{
        Addr:      EndPoint,
        Handler:   util.GrpcHandlerFunc(grpcServer, mux),
        TLSConfig: tlsConfig,
    }
}
```

#### `server`流程剖析

我们将这一大块代码，分成以下几个部分来理解

##### 一、启动监听

`net.Listen("tcp", EndPoint)`用于监听本地的网络地址通知，它的函数原型`func Listen(network, address string) (Listener, error)`

参数：`network`必须传入`tcp`、`tcp4`、`tcp6`、`unix`、`unixpacket`，若`address`为空或为0则会自动选择一个端口号
返回值：通过查看源码我们可以得知其返回值为`Listener`，结构体原型：
```
type Listener interface {
    Accept() (Conn, error)
    Close() error
    Addr() Addr
}
```

通过分析得知，**最后`net.Listen`会返回一个监听器的结构体，返回给接下来的动作，让其执行下一步的操作**，它可以执行三类操作
- `Accept`：接受等待并将下一个连接返回给`Listener`
- `Close`：关闭`Listener`
- `Addr`：返回`Listener`的网络地址

##### 二、获取`TLS`

通过`util.GetTLSConfig`解析得到`tls.Config`，传达给`http.Server`服务的`TLSConfig`配置项使用

##### 三、创建内部服务

`createInternalServer`函数，是整个服务端的核心流转部分

程序采用的是`HTT2`、`HTTPS`也就是需要支持`TLS`，因此在启动`grpc.NewServer`前，我们要将认证的中间件注册进去


而前面所获取的`tlsConfig`仅能给`HTTP`使用，因此**第一步**我们要创建`grpc`的`TLS`认证凭证

**1、创建`grpc`的`TLS`认证凭证**

新增引用`google.golang.org/grpc/credentials`的第三方包，它实现了`grpc`库支持的各种凭证，该凭证封装了客户机需要的所有状态，以便与服务器进行身份验证并进行各种断言，例如关于客户机的身份，角色或是否授权进行特定的呼叫

我们调用`NewServerTLSFromFile`来达到我们的目的，它能够从输入证书文件和服务器的密钥文件**构造TLS证书凭证**
```
func NewServerTLSFromFile(certFile, keyFile string) (TransportCredentials, error) {
    //LoadX509KeyPair读取并解析来自一对文件的公钥/私钥对
    cert, err := tls.LoadX509KeyPair(certFile, keyFile)
    if err != nil {
        return nil, err
    }
    //NewTLS使用tls.Config来构建基于TLS的TransportCredentials
    return NewTLS(&tls.Config{Certificates: []tls.Certificate{cert}}), nil
}
```

**2、设置`grpc ServerOption`**

以`grpc.Creds(creds)`为例，其原型为`func Creds(c credentials.TransportCredentials) ServerOption`，该函数返回`ServerOption`，它为服务器连接设置凭据


**3、创建`grpc`服务端**

函数原型：
```
func NewServer(opt ...ServerOption) *Server
```
我们在此处创建了一个没有注册服务的`grpc`服务端，还没有开始接受请求
```
grpcServer := grpc.NewServer(opts...)
```
**4、注册`grpc`服务**
```
pb.RegisterHelloWorldServer(grpcServer, NewHelloService())
```

**5、创建`grpc-gateway`关联组件**
```
ctx := context.Background()
dcreds, err := credentials.NewClientTLSFromFile(CertPemPath, CertName)
if err != nil {
    log.Println("Failed to create client TLS credentials %v", err)
}
dopts := []grpc.DialOption{grpc.WithTransportCredentials(dcreds)}
```
- `context.Background`：返回一个非空的空上下文。它没有被注销，没有值，没有过期时间。它通常由主函数、初始化和测试使用，并作为传入请求的**顶级上下文**
- `credentials.NewClientTLSFromFile`：从客户机的输入证书文件构造TLS凭证
- `grpc.WithTransportCredentials`：配置一个连接级别的安全凭据(例：`TLS`、`SSL`)，返回值为`type DialOption`
- `grpc.DialOption`：`DialOption`选项配置我们如何设置连接（其内部具体由多个的`DialOption`组成，决定其设置连接的内容）

**6、创建`HTTP NewServeMux`及注册`grpc-gateway`逻辑**
```
gwmux := runtime.NewServeMux()

// register grpc-gateway pb
if err := pb.RegisterHelloWorldHandlerFromEndpoint(ctx, gwmux, EndPoint, dopts); err != nil {
    log.Println("Failed to register gw server: %v\n", err)
}

// http服务
mux := http.NewServeMux()
mux.Handle("/", gwmux)
```

- `runtime.NewServeMux`：返回一个新的`ServeMux`，它的内部映射是空的；`ServeMux`是`grpc-gateway`的一个请求多路复用器。它将`http`请求与模式匹配，并调用相应的处理程序
- `RegisterHelloWorldHandlerFromEndpoint`：如函数名，注册`HelloWorld`服务的`HTTP Handle`到`grpc`端点
- `http.NewServeMux`：`分配并返回一个新的ServeMux`
- `mux.Handle`：为给定模式注册处理程序

（带着疑问去看程序）为什么`gwmux`可以放入`mux.Handle`中？

首先我们看看它们的原型是怎么样的

（1）`http.NewServeMux()`
```
func NewServeMux() *ServeMux {
        return new(ServeMux) 
}
```
```
type Handler interface {
    ServeHTTP(ResponseWriter, *Request)
}
```
（2）`runtime.NewServeMux`？
```
func NewServeMux(opts ...ServeMuxOption) *ServeMux {
    serveMux := &ServeMux{
        handlers:               make(map[string][]handler),
        forwardResponseOptions: make([]func(context.Context, http.ResponseWriter, proto.Message) error, 0),
        marshalers:             makeMarshalerMIMERegistry(),
    }
    ...
    return serveMux
}
```
（3）`http.NewServeMux()`的`Handle`方法
```
func (mux *ServeMux) Handle(pattern string, handler Handler)
```

通过分析可得知，两者`NewServeMux`都是最终返回`serveMux`，`Handler`中导出的方法仅有`ServeHTTP`，功能是用于响应HTTP请求

我们回到`Handle interface`中，可以得出结论就是任何结构体，只要实现了`ServeHTTP`方法，这个结构就可以称为`Handle`，`ServeMux`会使用该`Handler`调用`ServeHTTP`方法处理请求，这也就是**自定义`Handler`**

而我们这里正是将`grpc-gateway`中注册好的`HTTP Handler`无缝的植入到`net/http`的`Handle`方法中


**补充：在`go`中任何结构体只要实现了与接口相同的方法，就等同于实现了接口**

**7、注册具体服务**
```
if err := pb.RegisterHelloWorldHandlerFromEndpoint(ctx, gwmux, EndPoint, dopts); err != nil {
    log.Println("Failed to register gw server: %v\n", err)
}
```
在这段代码中，我们利用了前几小节的

- 上下文
- `gateway-grpc`的请求多路复用器
- 服务网络地址
- 配置好的安全凭据

注册了`HelloWorld`这一个服务

##### 四、创建`tls.NewListener`
```
func NewListener(inner net.Listener, config *Config) net.Listener {
    l := new(listener)
    l.Listener = inner
    l.config = config
    return l
}
```
`NewListener`将会创建一个`Listener`，它接受两个参数，第一个是来自内部`Listener`的监听器，第二个参数是`tls.Config`（必须包含至少一个证书）

##### 五、服务开始接受请求
在最后我们调用`srv.Serve(tls.NewListener(conn, tlsConfig))`，可以得知它是`http.Server`的方法，并且需要一个`Listener`作为参数，那么`Serve`内部做了些什么事呢？
```
func (srv *Server) Serve(l net.Listener) error {
    defer l.Close()
    ...

    baseCtx := context.Background() // base is always background, per Issue 16220
    ctx := context.WithValue(baseCtx, ServerContextKey, srv)
    for {
        rw, e := l.Accept()
        ...
        c := srv.newConn(rw)
        c.setState(c.rwc, StateNew) // before Serve can return
        go c.serve(ctx)
    }
}
```

粗略的看，它创建了一个`context.Background()`上下文对象，并调用`Listener`的`Accept`方法开始接受外部请求，在获取到连接数据后使用`newConn`创建连接对象，在最后使用`goroutine`的方式处理连接请求，达到其目的

**补充：对于`HTTP/2`支持，在调用`Serve`之前，应将`srv.TLSConfig`初始化为提供的`Listener`的TLS配置。如果`srv.TLSConfig`非零，并且在`Config.NextProtos`中不包含字符串`h2`，则不启用`HTTP/2`支持**

## 六、验证功能

### 编写测试客户端
在`grpc-hello-world/`下新建目录`client`，新建`client.go`文件，新增内容：
```
package main

import (
	"log"

	"golang.org/x/net/context"
	"google.golang.org/grpc"
	"google.golang.org/grpc/credentials"

	pb "grpc-hello-world/proto"
)

func main() {
	creds, err := credentials.NewClientTLSFromFile("../certs/server.pem", "dev")
	if err != nil {
		log.Println("Failed to create TLS credentials %v", err)
	}
	conn, err := grpc.Dial(":50052", grpc.WithTransportCredentials(creds))
	defer conn.Close()

	if err != nil {
		log.Println(err)
	}

	c := pb.NewHelloWorldClient(conn)
	context := context.Background()
	body := &pb.HelloWorldRequest{
		Referer : "Grpc",
	}

	r, err := c.SayHelloWorld(context, body)
	if err != nil {
		log.Println(err)
	}

	log.Println(r.Message)
}
```
由于客户端只是展示测试用，就简单的来了，原本它理应归类到`cobra`的管控下，配置管理等等都应可控化

在看这篇文章的你，可以试试将测试客户端归类好

### 启动服务端

回到`grpc-hello-world/`目录下，启动服务端`go run main.go server`，成功则仅返回
```
2018/02/26 17:19:36 gRPC and https listen on: 50052
```

### 执行测试客户端

回到`client`目录下，启动客户端`go run client.go`，成功则返回
```
2018/02/26 17:22:57 Grpc
```

### 执行测试Restful Api
```
curl -X POST -k https://localhost:50052/hello_world -d '{"referer": "restful_api"}'
```

成功则返回`{"message":"restful_api"}`

---

## 最终目录结构
```
grpc-hello-world
├── certs
│   ├── server.key
│   └── server.pem
├── client
│   └── client.go
├── cmd
│   ├── root.go
│   └── server.go
├── main.go
├── pkg
│   └── util
│       ├── grpc.go
│       └── tls.go
├── proto
│   ├── google
│   │   └── api
│   │       ├── annotations.pb.go
│   │       ├── annotations.proto
│   │       ├── http.pb.go
│   │       └── http.proto
│   ├── hello.pb.go
│   ├── hello.pb.gw.go
│   └── hello.proto
└── server
    ├── hello.go
    └── server.go
```

至此本节就结束了，推荐一下`jergoo`的文章，大家有时间可以看看

另外本节涉及了许多组件间的知识，值得大家细细的回味，非常有意义！

## 参考
### 示例代码
- [grpc-hello-world](https://github.com/EDDYCJY/grpc-hello-world)



================================================
FILE: content/posts/go/grpc-gateway/2018-03-04-swagger.md
================================================
---

title:      "「连载三」Swagger了解一下"
date:       2018-03-04 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc-gateway
---

在[上一节](https://segmentfault.com/a/1190000013408485)，我们完成了一个服务端同时支持`Rpc`和`RESTful Api`后，你以为自己大功告成了，结果突然发现要写`Api`文档和前端同事对接= = 。。。

你寻思有没有什么组件能够自动化生成`Api`文档来解决这个问题，就在这时你发现了`Swagger`，一起了解一下吧！

## 介绍
### Swagger
`Swagger`是全球最大的`OpenAPI`规范（OAS）API开发工具框架，支持从设计和文档到测试和部署的整个API生命周期的开发

`Swagger`是目前最受欢迎的`RESTful Api`文档生成工具之一，主要的原因如下
- 跨平台、跨语言的支持
- 强大的社区
- 生态圈 Swagger Tools（[Swagger Editor](https://github.com/swagger-api/swagger-editor)、[Swagger Codegen](https://github.com/swagger-api/swagger-codegen)、[Swagger UI](https://github.com/swagger-api/swagger-ui) ...）
- 强大的控制台

同时`grpc-gateway`也支持`Swagger`

[image]

### `OpenAPI`规范
`OpenAPI`规范是`Linux`基金会的一个项目，试图通过定义一种用来描述API格式或API定义的语言，来规范`RESTful`服务开发过程。`OpenAPI`规范帮助我们描述一个API的基本信息，比如：
- 有关该API的一般性描述
- 可用路径（/资源）
- 在每个路径上的可用操作（获取/提交...）
- 每个操作的输入/输出格式

目前V2.0版本的[OpenAPI规范](https://github.com/OAI/OpenAPI-Specification/blob/master/versions/2.0.md)（也就是SwaggerV2.0规范）已经发布并开源在github上。该文档写的非常好，结构清晰，方便随时查阅。

注：`OpenAPI`规范的介绍引用自[原文](https://huangwenchao.gitbooks.io/swagger/content/)

## 使用

### 生成`Swagger`的说明文件

**第一**，我们需要检查$GOBIN下是否包含`protoc-gen-swagger`可执行文件

若不存在则需要执行：
```
go get -u github.com/grpc-ecosystem/grpc-gateway/protoc-gen-swagger
```
等待执行完毕后，可在`$GOPATH/bin`下发现该执行文件，将其移动到`$GOBIN`下即可

**第二**，回到`$GOPATH/src/grpc-hello-world/proto`下，执行命令
```
protoc -I/usr/local/include -I. -I$GOPATH/src/grpc-hello-world/proto/google/api --swagger_out=logtostderr=true:. ./hello.proto
```
成功后执行`ls`即可看到`hello.swagger.json`文件


### 下载`Swagger UI`文件
`Swagger`提供可视化的`API`管理平台，就是[Swagger UI](https://github.com/swagger-api/swagger-ui)

我们将其源码下载下来，并将其`dist`目录下的所有文件拷贝到我们项目中的`$GOPATH/src/grpc-hello-world/third_party/swagger-ui`去

### 将`Swagger UI`转换为`Go`源代码

在这里我们使用的转换工具是[go-bindata](https://github.com/jteeuwen/go-bindata)

它支持将任何文件转换为可管理的`Go`源代码。用于将二进制数据嵌入到`Go`程序中。并且在将文件数据转换为原始字节片之前，可以选择压缩文件数据

#### 安装
```
go get -u github.com/jteeuwen/go-bindata/...
```
完成后，将`$GOPATH/bin`下的`go-bindata`移动到`$GOBIN`下

#### 转换
在项目下新建`pkg/ui/data/swagger`目录，回到`$GOPATH/src/grpc-hello-world/third_party/swagger-ui`下，执行命令
```
go-bindata --nocompress -pkg swagger -o pkg/ui/data/swagger/datafile.go third_party/swagger-ui/...
```

#### 检查
回到`pkg/ui/data/swagger`目录，检查是否存在`datafile.go`文件

### `Swagger UI`文件服务器（对外提供服务）
在这一步，我们需要使用与其配套的[go-bindata-assetfs](https://github.com/elazarl/go-bindata-assetfs/)

它能够使用`go-bindata`所生成`Swagger UI`的`Go`代码，结合`net/http`对外提供服务

#### 安装
```
go get github.com/elazarl/go-bindata-assetfs/...
```

#### 编写

通过分析，我们得知生成的文件提供了一个`assetFS`函数，该函数返回一个封装了嵌入文件的`http.Filesystem`，可以用其来提供一个`HTTP`服务

那么我们来编写`Swagger UI`的代码吧，主要是两个部分，一个是`swagger.json`，另外一个是`swagger-ui`的响应

##### serveSwaggerFile
引用包`strings`、`path`
```
func serveSwaggerFile(w http.ResponseWriter, r *http.Request) {
      if ! strings.HasSuffix(r.URL.Path, "swagger.json") {
        log.Printf("Not Found: %s", r.URL.Path)
        http.NotFound(w, r)
        return
    }

    p := strings.TrimPrefix(r.URL.Path, "/swagger/")
    p = path.Join("proto", p)

    log.Printf("Serving swagger-file: %s", p)

    http.ServeFile(w, r, p)
}
```
在函数中，我们利用`r.URL.Path`进行路径后缀判断

主要做了对`swagger.json`的文件访问支持（提供`https://127.0.0.1:50052/swagger/hello.swagger.json`的访问）

##### serveSwaggerUI
引用包`github.com/elazarl/go-bindata-assetfs`、`grpc-hello-world/pkg/ui/data/swagger`
```
func serveSwaggerUI(mux *http.ServeMux) {
    fileServer := http.FileServer(&assetfs.AssetFS{
        Asset:    swagger.Asset,
        AssetDir: swagger.AssetDir,
        Prefix:   "third_party/swagger-ui",
    })
    prefix := "/swagger-ui/"
    mux.Handle(prefix, http.StripPrefix(prefix, fileServer))
}
```

在函数中，我们使用了[go-bindata-assetfs](https://github.com/elazarl/go-bindata-assetfs/)来调度先前生成的`datafile.go`，结合`net/http`来对外提供`swagger-ui`的服务

#### 结合
在完成功能后，我们发现`path.Join("proto", p)`是写死参数的，这样显然不对，我们应该将其导出成外部参数，那么我们来最终改造一番

首先我们在`server.go`新增包全局变量`SwaggerDir`，修改`cmd/server.go`文件：
```
package cmd

import (
	"log"

	"github.com/spf13/cobra"
	
	"grpc-hello-world/server"
)

var serverCmd = &cobra.Command{
	Use:   "server",
	Short: "Run the gRPC hello-world server",
	Run: func(cmd *cobra.Command, args []string) {
		defer func() {
			if err := recover(); err != nil {
				log.Println("Recover error : %v", err)
			}
		}()
		
		server.Run()
	},
}

func init() {
	serverCmd.Flags().StringVarP(&server.ServerPort, "port", "p", "50052", "server port")
	serverCmd.Flags().StringVarP(&server.CertPemPath, "cert-pem", "", "./conf/certs/server.pem", "cert-pem path")
	serverCmd.Flags().StringVarP(&server.CertKeyPath, "cert-key", "", "./conf/certs/server.key", "cert-key path")
	serverCmd.Flags().StringVarP(&server.CertServerName, "cert-server-name", "", "grpc server name", "server's hostname")
	serverCmd.Flags().StringVarP(&server.SwaggerDir, "swagger-dir", "", "proto", "path to the directory which contains swagger definitions")
	
	rootCmd.AddCommand(serverCmd)
}
```

修改`path.Join("proto", p)`为`path.Join(SwaggerDir, p)`，这样的话我们`swagger.json`的文件路径就可以根据外部情况去修改它

最终`server.go`文件内容：
```
package server

import (
    "crypto/tls"
    "net"
    "net/http"
    "log"
    "strings"
    "path"

    "golang.org/x/net/context"
    "google.golang.org/grpc"
    "google.golang.org/grpc/credentials"
    "github.com/grpc-ecosystem/grpc-gateway/runtime"
    "github.com/elazarl/go-bindata-assetfs"
    
    pb "grpc-hello-world/proto"
    "grpc-hello-world/pkg/util"
    "grpc-hello-world/pkg/ui/data/swagger"
)

var (
    ServerPort string
    CertServerName string
    CertPemPath string
    CertKeyPath string
    SwaggerDir string
    EndPoint string

    tlsConfig *tls.Config
)

func Run() (err error) {
    EndPoint = ":" + ServerPort
    tlsConfig = util.GetTLSConfig(CertPemPath, CertKeyPath)

    conn, err := net.Listen("tcp", EndPoint)
    if err != nil {
        log.Printf("TCP Listen err:%v\n", err)
    }

    srv := newServer(conn)

    log.Printf("gRPC and https listen on: %s\n", ServerPort)

    if err = srv.Serve(util.NewTLSListener(conn, tlsConfig)); err != nil {
        log.Printf("ListenAndServe: %v\n", err)
    }

    return err
}
 
func newServer(conn net.Listener) (*http.Server) {
    grpcServer := newGrpc()
    gwmux, err := newGateway()
    if err != nil {
        panic(err)
    }

    mux := http.NewServeMux()
    mux.Handle("/", gwmux)
    mux.HandleFunc("/swagger/", serveSwaggerFile)
    serveSwaggerUI(mux)

    return &http.Server{
        Addr:      EndPoint,
        Handler:   util.GrpcHandlerFunc(grpcServer, mux),
        TLSConfig: tlsConfig,
    }
}

func newGrpc() *grpc.Server {
    creds, err := credentials.NewServerTLSFromFile(CertPemPath, CertKeyPath)
    if err != nil {
        panic(err)
    }

    opts := []grpc.ServerOption{
        grpc.Creds(creds),
    }
    server := grpc.NewServer(opts...)

    pb.RegisterHelloWorldServer(server, NewHelloService())

    return server
}

func newGateway() (http.Handler, error) {
    ctx := context.Background()
    dcreds, err := credentials.NewClientTLSFromFile(CertPemPath, CertServerName)
    if err != nil {
        return nil, err
    }
    dopts := []grpc.DialOption{grpc.WithTransportCredentials(dcreds)}
    
    gwmux := runtime.NewServeMux()
    if err := pb.RegisterHelloWorldHandlerFromEndpoint(ctx, gwmux, EndPoint, dopts); err != nil {
        return nil, err
    }

    return gwmux, nil
}

func serveSwaggerFile(w http.ResponseWriter, r *http.Request) {
      if ! strings.HasSuffix(r.URL.Path, "swagger.json") {
        log.Printf("Not Found: %s", r.URL.Path)
        http.NotFound(w, r)
        return
    }

    p := strings.TrimPrefix(r.URL.Path, "/swagger/")
    p = path.Join(SwaggerDir, p)

    log.Printf("Serving swagger-file: %s", p)

    http.ServeFile(w, r, p)
}

func serveSwaggerUI(mux *http.ServeMux) {
    fileServer := http.FileServer(&assetfs.AssetFS{
        Asset:    swagger.Asset,
        AssetDir: swagger.AssetDir,
        Prefix:   "third_party/swagger-ui",
    })
    prefix := "/swagger-ui/"
    mux.Handle(prefix, http.StripPrefix(prefix, fileServer))
}
```

## 测试
访问路径`https://127.0.0.1:50052/swagger/hello.swagger.json`，查看输出内容是否为`hello.swagger.json`的内容，例如：
[image]

访问路径`https://127.0.0.1:50052/swagger-ui/`，查看内容
[image]

## 小结

至此我们这一章节就完毕了，`Swagger`和其生态圈十分的丰富，有兴趣研究的小伙伴可以到其[官网](https://swagger.io/)认真研究

而目前完成的程度也满足了日常工作的需求了，可较自动化的生成`RESTful Api`文档，完成与接口对接


## 参考
### 示例代码
- [grpc-hello-world](https://github.com/EDDYCJY/grpc-hello-world)



================================================
FILE: content/posts/go/grpc-gateway/2019-06-22-grpc-gateway-tls.md
================================================
---

title:      "「连载四」gRPC+gRPC Gateway 能不能不用证书？"
date:       2019-06-22 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - grpc-gateway
---

如果你以前有涉猎过 gRPC+gRPC Gateway 这两个组件，你肯定会遇到这个问题，就是 **“为什么非得开 TLS，才能够实现同端口双流量，能不能不开？”** 又或是 **“我不想用证书就实现这些功能，行不行？”**。我被无数的人问过无数次这些问题，也说服过很多人，但说服归说服，不代表放弃。前年不行，不代表今年不行，在今天我希望分享来龙去脉和具体的实现方式给你。

![image](https://s2.ax1x.com/2020/02/27/3dLBAx.png)

## 过去

### 为什么 h2 不行

因为 `net/http2` 仅支持 "h2" 标识，而 "h2" 标识 HTTP/2 必须使用传输层安全性（TLS）的协议，此标识符用于 TLS 应用层协议协商字段以及识别 HTTP/2 over TLS。

简单来讲，也就 `net/http2` 必须使用 TLS 来交互。通俗来讲就要用证书，那么理所当然，也就无法支持非 TLS 的情况了。

### 寻找 h2c

那这条路不行，我们再想想别的路？那就是 HTTP/2 规范中的 "h2c" 标识了，"h2c" 标识允许通过明文 TCP 运行 HTTP/2 的协议，此标识符用于 HTTP/1.1 升级标头字段以及标识 HTTP/2 over TCP。

但是这条路，早在 2015 年就已经有在 [issue](https://github.com/golang/go/issues/13128#issuecomment-153193762) 中进行讨论，当时 @bradfitz 明确表示 “不打算支持 h2c，对仅支持 TLS 的情况非常满意，一年后再问我一次”，原文回复如下：

> We do not plan to support h2c. I don't want to receive bug reports from users who get bitten by transparent proxies messing with h2c. Also, until there's widespread browser support, it's not interesting. I am also not interested in being the chicken or the egg to get browser support going. I'm very happy with the TLS-only situation, and things like https://LetsEncrypt.org/ will make TLS much easier (and automatic) soon.

> Ask me again in one year.

### 琢磨其他方式

#### 使用 cmux

基于多路复用器 [soheilhy/cmux](https://github.com/soheilhy/cmux) 的另类实现 [Stoakes/grpc-gateway-example](https://github.com/Stoakes/grpc-gateway-example)。若对 `cmux` 的实现方式感兴趣，还可以看看 [《Golang: Run multiple services on one port》](https://blog.dgraph.io/post/cmux/)。

#### 使用第三方 h2

- [veqryn/h2c](https://github.com/veqryn/h2c)

这种属于自己实现了 h2c 的逻辑，以此达到效果。

## 现在

经过社区的不断讨论，最后在 2018 年 6 月，代表 "h2c" 标志的 `golang.org/x/net/http2/h2c` 标准库正式合并进来，自此我们就可以使用官方标准库（h2c），这个标准库实现了 HTTP/2 的未加密模式，因此我们就可以利用该标准库在同个端口上既提供 HTTP/1.1 又提供 HTTP/2 的功能了。

### 使用标准库 h2c 

```
import (
	...

	"golang.org/x/net/http2"
	"golang.org/x/net/http2/h2c"
	"google.golang.org/grpc"

	"github.com/grpc-ecosystem/grpc-gateway/runtime"

	pb "github.com/EDDYCJY/go-grpc-example/proto"
)

...

func grpcHandlerFunc(grpcServer *grpc.Server, otherHandler http.Handler) http.Handler {
	return h2c.NewHandler(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		if r.ProtoMajor == 2 && strings.Contains(r.Header.Get("Content-Type"), "application/grpc") {
			grpcServer.ServeHTTP(w, r)
		} else {
			otherHandler.ServeHTTP(w, r)
		}
	}), &http2.Server{})
}

func main() {
	server := grpc.NewServer()

	pb.RegisterSearchServiceServer(server, &SearchService{})

	mux := http.NewServeMux()
	gwmux := runtime.NewServeMux()
	dopts := []grpc.DialOption{grpc.WithInsecure()}

	err := pb.RegisterSearchServiceHandlerFromEndpoint(context.Background(), gwmux, "localhost:"+PORT, dopts)
	...
	mux.Handle("/", gwmux)
	http.ListenAndServe(":"+PORT, grpcHandlerFunc(server, mux))
}
```

我们可以看到关键之处在于调用了 `h2c.NewHandler` 方法进行了特殊处理，`h2c.NewHandler` 会返回一个 `http.handler`，主要的内部逻辑是拦截了所有 `h2c` 流量，然后根据不同的请求流量类型将其劫持并重定向到相应的 `Hander` 中去处理。

### 验证

#### HTTP/1.1

```
$ curl -X GET 'http://127.0.0.1:9005/search?request=EDDYCJY'
{"response":"EDDYCJY"}
```

#### HTTP/2(gRPC)

```
...
func main() {
	conn, err := grpc.Dial(":"+PORT, grpc.WithInsecure())
	...
	client := pb.NewSearchServiceClient(conn)
	resp, err := client.Search(context.Background(), &pb.SearchRequest{
		Request: "gRPC",
	})
}
```
输出结果：

```
$ go run main.go
2019/06/21 20:04:09 resp: gRPC h2c Server
```

## 总结

在本文中我介绍了大致的前因后果，且介绍了几种解决方法，我建议你选择官方的 `h2c` 标准库去实现这个功能，也简单。在最后，不管你是否曾经为这个问题烦恼过许久，又或者正在纠结，都希望这篇文章能够帮到你。

## 参考

- https://github.com/golang/go/issues/13128
- https://github.com/golang/go/issues/14141
- https://github.com/golang/net/commit/c4299a1a0d8524c11563db160fbf9bddbceadb21
- https://go-review.googlesource.com/c/net/+/112997/


================================================
FILE: content/posts/go/import-cyc.md
================================================
---
title: "为什么 Go 不支持循环引用？"
date: 2021-12-31T12:55:15+08:00
toc: true
images:
tags: 
  - go
  - 为什么
---

大家好，我是煎鱼。

近年来开始学习 Go 语言的开发者越来越多了。很多小伙伴在使用时，就会遇到种种不理解的问题。

其中一点就是循环引入的报错：

```shell
package command-line-arguments
	imports github.com/eddycjy/awesome-project/a
	imports github.com/eddycjy/awesome-project/b
	imports github.com/eddycjy/awesome-project/a: import cycle not allowed
```

为什么 Go 不支持循环引用呢，这就很不解了，难道还影响性能了？


![图来自网络](https://files.mdnice.com/user/3610/4596a6d1-9286-40b2-8074-cc43f9bbd9f4.png)

今天煎鱼将和大家一起了解背后的原因。

## 案例演示

做一个基本的案例 Demo，便于没接触过的同学建立初步认知。我们的程序分别有 2 个 package。

package a 的代码如下：

```golang
import (
	"github.com/eddycjy/awesome-project/b"
)

func Hello(s string) {
	b.Print(s)
}
```

package b 的代码如下：

```golang
import (
	"fmt"

	"github.com/eddycjy/awesome-project/a"
)

func Hello() {
	a.Hello("脑子进煎鱼了")
}

func Print(s string) {
	fmt.Println(s)
}
```

再在 main.go 的文件中调用 `a.Hello("脑子进煎鱼了")` 方法。

一运行，就会出现如下错误提示：

```shell
package command-line-arguments
	imports github.com/eddycjy/awesome-project/a
	imports github.com/eddycjy/awesome-project/b
	imports github.com/eddycjy/awesome-project/a: import cycle not allowed
```

错误的本质原因是 package a 引用了 package b，而 package b 又引用了 package a，造成了循环引用。

这在 Go 语言中是明令禁止的，在编译时就会中断程序，导致编译失败。

## 原因分析

根据现在 Go 官方的统一意见来看，package 循环导入几乎不可能出现，即使是 Go2。

因为 Go2 可能是很多核心问题的破变的关键节点，有许多人提了类似《[proposal: Go 2: allow import cycle](https://github.com/golang/go/issues/30247)》的提案，希望解决循环引入的问题。

Go 语言之父 Rob Pike 亲自回答了这个问题，原因如下：

- 没有支持循环导入，目的是迫使 Go 程序员更多地考虑程序的依赖关系。
    - 保持依赖关系图的简洁。
    - 快速的程序构建。
- 如果支持循环导入，很容易会造成懒惰、不良的依赖性管理和缓慢的构建。这是设计者不希望看见的。
    - 混乱的依赖关系。
    - 缓慢的程序构建

简单拿来就，就是在 Go 工程中出现循环引用，这会对构建性能和依赖关系的解决非常不利。

为此，考虑一开始就保持图的正确 DAG，认为这是一个值得预先简化的领域。导入循环可能很方便，但其实背后的代价可能是灾难性的，所以在 Go 中被明确禁止支持。

## 总结

在程序中，如果我们频繁的出现模块与模块之间的循环引用，这时候我们是不是应该考虑一下，是不是设计的有些问题，要不要考虑调整？

但也并非所有的事都是二极管，Go 源码可能或多或少都有自己循环引用的案例，最重要的是想清楚。

**你对此支持循环引用怎么看**，欢迎在评论区留言交流：）


================================================
FILE: content/posts/go/import-generics.md
================================================
---
title: "长达 12 年，Go 才引入泛型，是政治，还是技术问题？"
date: 2021-12-31T12:55:25+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前两天 Go1.18 beta1 已经发布，距离正式发布 Go1.18 的生产可用还有 2 个月，也就是泛型即将正式面世。

最近正在收集泛型的一些资料，看到在 2015 年有人在 Hacker News 上的《[Go 1.5 max procs default](https://news.ycombinator.com/item?id=9622417 "Go 1.5 max procs default")》吐槽 Go 不支持泛型是 “政治” 原因...

看了还是有些意义的，**与现在的矛盾点基本一致**，为此分享给大家。

## 网友吐槽

网友 @aikah 认为 Go 团队不太可能在语言中加入泛型，这显然是一个政治问题而不是技术问题。错误处理也是如此。

和许多人一样，该网友**认为 Go 在极简主义和功能之间没有取得正确的平衡**。反对泛型的人赞成用编译时类型检查（总是安全的）换取运行时类型断言（可能失败）。

他们拒绝承认这一事实。这就是他们反对泛型的论点，并将最终损害语言的任何潜在增长。他们基本上是在违背自己的利益。

## 官方回复

Russ Cox 做了正式的回复：很抱歉，但不是：**泛型是一个技术问题**，不是一个政治问题。

Go 团队并**不反对泛型本身**，只是反对做那些没有被很好理解或不能很好地与 Go 配合的事情。

这就是核心观点和矛盾点，也从 2009 年，延续到了现在。

### 会遇到的问题

Go 团队认为要将泛型的概念融入 Go，并与系统的其他部分很好地配合，必须解决一些深层次的技术问题，而我们并没有解决这些问题的办法。

关于这些问题，在几年前就在博客上写过一篇《[The Generic Dilemma](https://research.swtch.com/generic "The Generic Dilemma")》：

![](https://files.mdnice.com/user/3610/8ed3923a-d5fc-482f-bb6d-6fff7a19fcaa.png)

即使克服了那一页上的问题，也有其他问题，接下来你会遇到的问题是：”如何让程序员以一种有用的、易于解释的方式省略类型注释“。

也就是如何更人性、更易于的表达泛型的类型参数。

#### 泛型例子

举个例子，C++ 允许你写 `make_pair(1, "foo")`，而不是 `make_pair<int, string>(1, "foo")`。

为了达到这种效果，推断注释背后的逻辑需要几页几页的规范，这并不是一个特别容易理解的编程模型，当事情出错时，编译器也不能轻易解释。

在这之后肯定还有更多的新问题在这里面。

#### 和专家沟通

Go 团队和一些真正的 Java 泛型专家谈过，他们每个人都说了大致相同的话：要非常小心，它不像看起来那么容易，而且你会被你犯的所有错误困住。

作为一个 Java 示范，可以浏览一下《[Java Generics FAQs - Frequently Asked Questions](http://www.angelikalanger.com/GenericsFAQ/JavaGenericsFAQ.html "Java Generics FAQs - Frequently Asked Questions")》的大部分内容：

![](https://files.mdnice.com/user/3610/6e188c16-f31c-4d6b-9d1b-216aa702d548.png)

看看过了多久你会开始思考 "这真的是最好的方法吗？"。

在泛型过程中会遇到许多问题，像是《[How do I decrypt Enum<E extends Enum<E>>](http://www.angelikalanger.com/GenericsFAQ/FAQSections/TypeParameters.html#FAQ106" "How do I decrypt Enum<E extends Enum<E>>")》：

![](https://files.mdnice.com/user/3610/2cbd8083-cee6-48f7-a0bd-d6faf8d27c40.png)

为此，Go 团队在泛型的推动上非常谨慎。
  
## 承认缺点

Go 团队说得很清楚，承认这个事实：**没有泛型是有一定的缺点的**。
  
你要么使用 `interface{}` 而放弃编译时检查，要么写代码生成器而使你的构建过程复杂化。

现有语言中实现的泛型也有明确的缺点，而且今天不妥协有一个非常大的好处：它使明天**采用更好的解决方案变得更加容易**。

## 总结
  
今天给大家分享了过去在国外社区针对 Go 泛型的各种争议和探讨，其实泛型的核心观点很明确：”Go 团队不反对泛型本身“。
  
一直没能把泛型做起来，也是因为顾虑很多，做泛型要和 Go 多个部分，要解决很多深层次的问题，还要解决类型参数可读性等问题。所以一直拖到了现在。
  
回到即将 2022 年的现在，都预言对了。社区都在扯做泛型后的多个关联组件，以及泛型可读性和结构...

显然，**泛型就是双刃剑？你怎么看**。

================================================
FILE: content/posts/go/len.md
================================================
---
title: "迷惑了，Go len() 是怎么计算出来的？"
date: 2021-12-31T12:54:58+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

最近看到了一个很有意思的话题，我们平时常常会用 Go 的内置函数 `len` 去获取各种 map、slice 的长度，那他是怎么实现的呢？

正当我想去看看 `len` 的具体实现时，一展身手，却发现竟然是个空方法：

```golang
func len(v Type) int
```

看注解也没有 link 到其他 runtime 函数，那么 len 函数是如何被调用的呢？

先前看国外讨论 Go 计算 len 的文章时做了一些翻译和笔记（底下有参考链接），在此分享给大家，共同进步。

## 谜底

今天就由煎鱼带大家一同解开这个谜底。既然是谜底，那就一开始就揭开。

其实 Go 语言中并没有 len 函数的具体实现代码，他其实**是 Go 编译器的 "魔法" ，不是实际的函数调用**。

接下来将展开这部分，我们可以更深入地了解 Go 编译器的内部工作原理。

## 编译器

在 Go 编译器编译时会解析命令行参数中指定的标志和 Go 源文件，对解析后的 Go 包进行类型检查，将函数编译为机器代码。代码，最后将编译后的包定义写到磁盘上。

内部定义基本类型、内置函数和操作函数的阶段是在 types/universe.go 当中。同时会进行内置函数和具体的操作符匹配，可以明确知道内置函数 len 对应的是 OLEN：

```golang
var builtinFuncs = [...]struct {
	name string
	op   Op
}{
	{"append", OAPPEND},
	{"cap", OCAP},
	{"close", OCLOSE},
	{"complex", OCOMPLEX},
	{"copy", OCOPY},
	{"delete", ODELETE},
	{"imag", OIMAG},
	{"len", OLEN},
	...
}
```

在编译时，上分为五个阶段进行类型检查：
- 第一阶段：常量、类型、以及函数的名称和类型。
- 第二阶段：变量赋值、接口赋值、别名声明。
- 第三阶段：类型检查函数体。
- 第四阶段：检查外部声明。
- 第五阶段：检查类型的地图键，未使用的导入。

如果最后一个类型检查阶段遇到 len 函数，就会转换为 UnaryExpr 类型，一个 UnaryExpr 节点代表一个单数表达式，也最终就是不会成为函数调用：

```golang
func typecheck1(n ir.Node, top int) ir.Node {
	if n, ok := n.(*ir.Name); ok {
		typecheckdef(n)
	}

	switch n.Op() {
	...
	case ir.OCAP, ir.OLEN:
		n := n.(*ir.UnaryExpr)
		return tcLenCap(n)
	}
}
```

在调用 `*ir.UnaryExpr` 转换完毕后，会调用 `tcLenCap`，也就是 typecheck，使用 okforlen 数组来验证参数的合法性或发出相关错误信息：

```golang
func tcLenCap(n *ir.UnaryExpr) ir.Node {
	n.X = Expr(n.X)
	n.X = DefaultLit(n.X, nil)
	n.X = implicitstar(n.X)
	...
	var ok bool
	if n.Op() == ir.OLEN {
		ok = okforlen[t.Kind()]
	} else {
		ok = okforcap[t.Kind()]
	}
  
	...
	n.SetType(types.Types[types.TINT])
	return n
}
```

经历过上面的步骤后在对所有内容进行类型检查后，所有函数都将排队等待编译：

```golang
	base.Timer.Start("be", "compilefuncs")
	fcount := int64(0)
	for i := 0; i < len(typecheck.Target.Decls); i++ {
		if fn, ok := typecheck.Target.Decls[i].(*ir.Func); ok {
			enqueueFunc(fn)
			fcount++
		}
	}
	base.Timer.AddEvent(fcount, "funcs")

	compileFunctions()
```

在经过在 buildssa 和 genssa 之后，再深入几层，就会将 AST 树中的 len 表达式转换为 SSA。接着我们就可以看到 Go 语言中的每种类型的长度是怎么获取的。

这块的处理对应 internal/ssagen/ssa.go 的 expr 方法，如下：

```golang
	case ir.OLEN, ir.OCAP:
		n := n.(*ir.UnaryExpr)
		switch {
		case n.X.Type().IsSlice():
			op := ssa.OpSliceLen
			if n.Op() == ir.OCAP {
				op = ssa.OpSliceCap
			}
			return s.newValue1(op, types.Types[types.TINT], s.expr(n.X))
		case n.X.Type().IsString(): // string; not reachable for OCAP
			return s.newValue1(ssa.OpStringLen, types.Types[types.TINT], s.expr(n.X))
		case n.X.Type().IsMap(), n.X.Type().IsChan():
			return s.referenceTypeBuiltin(n, s.expr(n.X))
		default: // array
			return s.constInt(types.Types[types.TINT], n.X.Type().NumElem())
		}
```

若是数组（array）类型，则会调用 `NumElem` 方法来获取长度值：

```golang
type Array struct {
	Elem  *Type 
	Bound int64 
}

func (t *Type) NumElem() int64 {
	t.wantEtype(TARRAY)
	return t.Extra.(*Array).Bound
}
```

若是字典（map）类型或通道（channel），将会调用 `referenceTypeBuiltin` 方法：

```golang
func (s *state) referenceTypeBuiltin(n *ir.UnaryExpr, x *ssa.Value) *ssa.Value {
	lenType := n.Type()
	nilValue := s.constNil(types.Types[types.TUINTPTR])
	cmp := s.newValue2(ssa.OpEqPtr, types.Types[types.TBOOL], x, nilValue)
	b := s.endBlock()
	b.Kind = ssa.BlockIf
	b.SetControl(cmp)
	b.Likely = ssa.BranchUnlikely

	bThen := s.f.NewBlock(ssa.BlockPlain)
	bElse := s.f.NewBlock(ssa.BlockPlain)
	bAfter := s.f.NewBlock(ssa.BlockPlain)
	...
	switch n.Op() {
	case ir.OLEN:
		s.vars[n] = s.load(lenType, x)
	...
	return s.variable(n, lenType)
}
```

该函数的作用是是获取 map 或chan 的内存地址，并以零偏移量引用其结构布局，就像 `unsafe.Pointer(uintptr(unsafe.Pointer(s))` 一样，返回第一个字面字段的值。

那为什么要获取结构体的第一个字段的值呢，应该是和 map 和 chan 的基础数据结构有关：

```golang
type hmap struct {
	count     int 
  ...
}

type hchan struct {
	qcount   uint    
	...
}
```

是因为 map 和 chan 的基础数据结构的第一个字段就表示长度，自然也就通过计算偏移值来获取了。

其他的数据类型，大家可以继续深入代码，再细看就好了。主要还是枚举多同类的数据类型，接着调用相应的方法。

## 总结

每次我们看到内置函数时，总会下意识的以为是在 runtime 内实现的。看不到 runtime 内的实现方法，又会以为是通过注解 link 的方式来解决的。

但需要注意，其实还有像 len 内置函数这种直接编译器转换的，这也是一种不错的优化方式。

## 参考
- https://tpaschalis.github.io/golang-len
- https://stackoverflow.com/questions/28204831/how-do-os-len-and-make-functions-work

================================================
FILE: content/posts/go/map/2019-03-05-map-access.md
================================================
---

title:      "深入理解 Go map：初始化和访问元素"
date:       2019-03-05 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

从本文开始咱们一起探索 Go map 里面的奥妙吧，看看它的内在是怎么构成的，又分别有什么值得留意的地方？

第一篇将探讨**初始化和访问元素**相关板块，咱们带着疑问去学习，例如：

- 初始化的时候会马上分配内存吗？
- 底层数据是如何存储的？
- 底层是如何使用 key 去寻找数据的？
- 底层是用什么方式解决哈希冲突的？
- 数据类型那么多，底层又是怎么处理的呢？

...

## 数据结构

首先我们一起看看 Go map 的基础数据结构，先有一个大致的印象

![image](https://s2.ax1x.com/2020/02/27/3dLgjH.png)

### hmap

```go
type hmap struct {
	count     int
	flags     uint8
	B         uint8
	noverflow uint16
	hash0     uint32
	buckets    unsafe.Pointer
	oldbuckets unsafe.Pointer
	nevacuate  uintptr
	extra *mapextra
}

type mapextra struct {
	overflow    *[]*bmap
	oldoverflow *[]*bmap
	nextOverflow *bmap
}
```

- count：map 的大小，也就是 len() 的值。代指 map 中的键值对个数
- flags：状态标识，主要是 goroutine 写入和扩容机制的相关状态控制。并发读写的判断条件之一就是该值
- B：桶，最大可容纳的元素数量，值为 **负载因子（默认 6.5） \* 2 ^ B**，是 2 的指数
- noverflow：溢出桶的数量
- hash0：哈希因子
- buckets：保存当前桶数据的指针地址（指向一段连续的内存地址，主要存储键值对数据）
- oldbuckets，保存旧桶的指针地址
- nevacuate：迁移进度
- extra：原有 buckets 满载后，会发生扩容动作，在 Go 的机制中使用了增量扩容，如下为细项：
  - `overflow` 为 `hmap.buckets` （当前）溢出桶的指针地址
  - `oldoverflow` 为 `hmap.oldbuckets` （旧）溢出桶的指针地址
  - `nextOverflow` 为空闲溢出桶的指针地址

在这里我们要注意几点，如下：

1. 如果 keys 和 values 都不包含指针并且允许内联的情况下。会将 bucket 标识为不包含指针，使用 extra 存储溢出桶就可以避免 GC 扫描整个 map，节省不必要的开销
2. 在前面有提到，Go 用了增量扩容。而 `buckets` 和 `oldbuckets` 也是与扩容相关的载体，一般情况下只使用 `buckets`，`oldbuckets` 是为空的。但如果正在扩容的话，`oldbuckets` 便不为空，`buckets` 的大小也会改变
3. 当 `hint` 大于 8 时，就会使用 `*mapextra` 做溢出桶。若小于 8，则存储在 buckets 桶中

### bmap

![image](https://s2.ax1x.com/2020/02/27/3dLz5V.png)

```go
bucketCntBits = 3
bucketCnt     = 1 << bucketCntBits
...
type bmap struct {
	tophash [bucketCnt]uint8
}
```

- tophash：key 的 hash 值高 8 位
- keys：8 个 key
- values：8 个 value
- overflow：下一个溢出桶的指针地址（当 hash 冲突发生时）

实际 bmap 就是 buckets 中的 bucket，一个 bucket 最多存储 8 个键值对

#### tophash

tophash 是个长度为 8 的数组，代指桶最大可容纳的键值对为 8。

存储每个元素 hash 值的高 8 位，如果 `tophash [0] <minTopHash`，则 `tophash [0]` 表示为迁移进度

#### keys 和 values

在这里我们留意到，存储 k 和 v 的载体并不是用 `k/v/k/v/k/v/k/v` 的模式，而是 `k/k/k/k/v/v/v/v` 的形式去存储。这是为什么呢？

```go
map[int64]int8
```

在这个例子中，如果按照 `k/v/k/v/k/v/k/v` 的形式存放的话，虽然每个键值对的值都只占用 1 个字节。但是却需要 7 个填充字节来补齐内存空间。最终就会造成大量的内存 “浪费”

![image](https://s2.ax1x.com/2020/02/27/3dOK2D.png)

但是如果以 `k/k/k/k/v/v/v/v` 的形式存放的话，就能够解决因对齐所 "浪费" 的内存空间

因此这部分的拆分主要是考虑到内存对齐的问题，虽然相对会复杂一点，但依然值得如此设计

![image](https://s2.ax1x.com/2020/02/27/3dODqs.png)

#### overflow

可能会有同学疑惑为什么会有溢出桶这个东西？实际上在不存在哈希冲突的情况下，去掉溢出桶，也就是只需要桶、哈希因子、哈希算法。也能实现一个简单的 hash table。但是哈希冲突（碰撞）是不可避免的...

而在 Go map 中当 `hmap.buckets` 满了后，就会使用溢出桶接着存储。我们结合分析可确定 Go 采用的是数组 + 链地址法解决哈希冲突

![image](https://s2.ax1x.com/2020/02/27/3dO7Ix.png)

## 初始化

### 用法

```go
m := make(map[int32]int32)
```

### 函数原型

通过阅读源码可得知，初始化方法有好几种。函数原型如下：

```go
func makemap_small() *hmap
func makemap64(t *maptype, hint int64, h *hmap) *hmap
func makemap(t *maptype, hint int, h *hmap) *hmap
```

- makemap_small：当 `hint` 小于 8 时，会调用 `makemap_small` 来初始化 hmap。主要差异在于是否会马上初始化 hash table
- makemap64：当 `hint` 类型为 int64 时的特殊转换及校验处理，后续实质调用 `makemap`
- makemap：实现了标准的 map 初始化动作

### 源码

```go
func makemap(t *maptype, hint int, h *hmap) *hmap {
	if hint < 0 || hint > int(maxSliceCap(t.bucket.size)) {
		hint = 0
	}

	if h == nil {
		h = new(hmap)
	}
	h.hash0 = fastrand()

	B := uint8(0)
	for overLoadFactor(hint, B) {
		B++
	}
	h.B = B

	if h.B != 0 {
		var nextOverflow *bmap
		h.buckets, nextOverflow = makeBucketArray(t, h.B, nil)
		if nextOverflow != nil {
			h.extra = new(mapextra)
			h.extra.nextOverflow = nextOverflow
		}
	}

	return h
}
```

- 根据传入的 `bucket` 类型，获取其类型能够申请的最大容量大小。并对其长度 `make(map[k]v, hint)` 进行边界值检验
- 初始化 hmap
- 初始化哈希因子
- 根据传入的 `hint`，计算一个可以放下 `hint` 个元素的桶 `B` 的最小值
- 分配并初始化 hash table。如果 `B` 为 0 将在后续懒惰分配桶，大于 0 则会马上进行分配
- 返回初始化完毕的 hmap

在这里可以注意到，（当 `hint` 大于等于 8 ）第一次初始化 map 时，就会通过调用 `makeBucketArray` 对 buckets 进行分配。因此我们常常会说，在初始化时指定一个适当大小的容量。能够提升性能。

若该容量过少，而新增的键值对又很多。就会导致频繁的分配 buckets，进行扩容迁移等 rehash 动作。最终结果就是性能直接的下降（敲黑板）

而当 `hint` 小于 8 时，这种问题**相对**就不会凸显的太明显，如下：

```go
func makemap_small() *hmap {
	h := new(hmap)
	h.hash0 = fastrand()
	return h
}
```

### 图示

![image](https://s2.ax1x.com/2020/02/27/3dOLRO.png)

## 访问

### 用法

```
v := m[i]
v, ok := m[i]
```

### 函数原型

在实现 map 元素访问上有好几种方法，主要是包含针对 32/64 位、string 类型的特殊处理，总的函数原型如下：

```go
mapaccess1(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer
mapaccess2(t *maptype, h *hmap, key unsafe.Pointer) (unsafe.Pointer, bool)

mapaccessK(t *maptype, h *hmap, key unsafe.Pointer) (unsafe.Pointer, unsafe.Pointer)

mapaccess1_fat(t *maptype, h *hmap, key, zero unsafe.Pointer) unsafe.Pointer
mapaccess2_fat(t *maptype, h *hmap, key, zero unsafe.Pointer) (unsafe.Pointer, bool)

mapaccess1_fast32(t *maptype, h *hmap, key uint32) unsafe.Pointer
mapaccess2_fast32(t *maptype, h *hmap, key uint32) (unsafe.Pointer, bool)
mapassign_fast32(t *maptype, h *hmap, key uint32) unsafe.Pointer
mapassign_fast32ptr(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer

mapaccess1_fast64(t *maptype, h *hmap, key uint64) unsafe.Pointer
...

mapaccess1_faststr(t *maptype, h *hmap, ky string) unsafe.Pointer
...
```

- mapaccess1：返回 `h[key]` 的指针地址，如果键不在 `map` 中，将返回对应类型的零值
- mapaccess2：返回 `h[key]` 的指针地址，如果键不在 `map` 中，将返回零值和布尔值用于判断

### 源码

```go
func mapaccess1(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
	...
	if h == nil || h.count == 0 {
		return unsafe.Pointer(&zeroVal[0])
	}
	if h.flags&hashWriting != 0 {
		throw("concurrent map read and map write")
	}
	alg := t.key.alg
	hash := alg.hash(key, uintptr(h.hash0))
	m := bucketMask(h.B)
	b := (*bmap)(add(h.buckets, (hash&m)*uintptr(t.bucketsize)))
	if c := h.oldbuckets; c != nil {
		if !h.sameSizeGrow() {
			// There used to be half as many buckets; mask down one more power of two.
			m >>= 1
		}
		oldb := (*bmap)(add(c, (hash&m)*uintptr(t.bucketsize)))
		if !evacuated(oldb) {
			b = oldb
		}
	}
	top := tophash(hash)
	for ; b != nil; b = b.overflow(t) {
		for i := uintptr(0); i < bucketCnt; i++ {
			if b.tophash[i] != top {
				continue
			}
			k := add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
			if t.indirectkey {
				k = *((*unsafe.Pointer)(k))
			}
			if alg.equal(key, k) {
				v := add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.valuesize))
				if t.indirectvalue {
					v = *((*unsafe.Pointer)(v))
				}
				return v
			}
		}
	}
	return unsafe.Pointer(&zeroVal[0])
}
```

- 判断 map 是否为 nil，长度是否为 0。若是则返回零值
- 判断当前是否并发读写 map，若是则抛出异常
- 根据 key 的不同类型调用不同的 hash 方法计算得出 hash 值
- 确定 key 在哪一个 bucket 中，并得到其位置
- 判断是否正在发生扩容（h.oldbuckets 是否为 nil），若正在扩容，则到老的 buckets 中查找（因为 buckets 中可能还没有值，搬迁未完成），若该 bucket 已经搬迁完毕。则到 buckets 中继续查找
- 计算 hash 的 tophash 值（高八位）
- 根据计算出来的 tophash，依次循环对比 buckets 的 tophash 值（快速试错）
- 如果 tophash 匹配成功，则计算 key 的所在位置，正式完整的对比两个 key 是否一致
- 若查找成功并返回，若不存在，则返回零值

在上述步骤三中，提到了根据不同的类型计算出 hash 值，另外会计算出 hash 值的高八位和低八位。低八位会作为 bucket index，作用是用于找到 key 所在的 bucket。而高八位会存储在 bmap tophash 中

其主要作用是在上述步骤七中进行迭代快速定位。这样子可以提高性能，而不是一开始就直接用 key 进行一致性对比

### 图示

![image](https://s2.ax1x.com/2020/02/27/3dOOzD.png)

## 总结

在本章节，我们介绍了 map 类型的以下知识点：

- map 的基础数据结构
- 初始化 map
- 访问 map

从阅读源码中，得知 Go 本身**对于一些不同大小、不同类型的属性，包括哈希方法都有编写特定方法**去运行。总的来说，这块的设计隐含较多的思路，有不少点值得细细品尝 :)

注：本文基于 Go 1.11.5


================================================
FILE: content/posts/go/map/2019-03-24-map-assign.md
================================================
---

title:      "深入理解 Go map：赋值和扩容迁移"
date:       2019-03-24 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

## 概要

在 [上一章节](https://book.eddycjy.com/golang/map/map-access.html) 中，数据结构小节里讲解了大量基础字段，可能你会疑惑需要 #&（！……#（！￥！ 来干嘛？接下来我们一起简单了解一下基础概念。再开始研讨今天文章的重点内容。我相信这样你能更好的读懂这篇文章

### 哈希函数

哈希函数，又称散列算法、散列函数。主要作用是通过特定算法将数据根据一定规则组合重新生成得到一个**散列值**

而在哈希表中，其生成的散列值常用于寻找其键映射到哪一个桶上。而一个好的哈希函数，应当尽量少的出现哈希冲突，以此保证操作哈希表的时间复杂度（但是哈希冲突在目前来讲，是无法避免的。我们需要 “解决” 它）

![image](http://wx3.sinaimg.cn/large/006fVPCvly1g161h7r7hgj30is0dmjro.jpg)

### 链地址法

在哈希操作中，相当核心的一个处理动作就是 “哈希冲突” 的解决。而在 Go map 中采用的就是 "链地址法 " 去解决哈希冲突，又称 "拉链法"。其主要做法是数组 + 链表的数据结构，其溢出节点的存储内存都是动态申请的，因此相对更灵活。而每一个元素都是一个链表。如下图：

![image](http://wx4.sinaimg.cn/large/006fVPCvly1g1dw2b8t0ej30e60cy747.jpg)

### 桶/溢出桶

```go
type hmap struct {
	...
	buckets    unsafe.Pointer
    ...
	extra *mapextra
}

type mapextra struct {
	overflow    *[]*bmap
	oldoverflow *[]*bmap
	nextOverflow *bmap
}
```

在上章节中，我们介绍了 Go map 中的桶和溢出桶的概念，在其桶中只能存储 8 个键值对元素。当超过 8 个时，将会使用溢出桶进行存储或进行扩容

你可能会有疑问，hint 大于 8 又会怎么样？答案很明显，性能问题，其时间复杂度改变（也就是执行效率出现问题）

## 前言

概要复习的差不多后，接下来我们将一同研讨 Go map 的另外三个核心行为：赋值、扩容、迁移。正式开始我们的研讨之旅吧 ：）

## 赋值

```go
m := make(map[int32]string)
m[0] = "EDDYCJY"
```

### 函数原型

在 map 的赋值动作中，依旧是针对 32/64 位、string、pointer 类型有不同的转换处理，总的函数原型如下：

```go
func mapassign(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer
func mapaccess1_fast32(t *maptype, h *hmap, key uint32) unsafe.Pointer
func mapaccess2_fast32(t *maptype, h *hmap, key uint32) (unsafe.Pointer, bool)
func mapassign_fast32(t *maptype, h *hmap, key uint32) unsafe.Pointer
func mapassign_fast32ptr(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer

func mapaccess1_fast64(t *maptype, h *hmap, key uint64) unsafe.Pointer
func mapaccess2_fast64(t *maptype, h *hmap, key uint64) (unsafe.Pointer, bool)
func mapassign_fast64(t *maptype, h *hmap, key uint64) unsafe.Pointer
func mapassign_fast64ptr(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer
func mapaccess1_faststr(t *maptype, h *hmap, ky string) unsafe.Pointer
func mapaccess2_faststr(t *maptype, h *hmap, ky string) (unsafe.Pointer, bool)
func mapassign_faststr(t *maptype, h *hmap, s string) unsafe.Pointer
...
```

接下来我们将分成几个部分去看看底层在赋值的时候，都做了些什么处理？

### 源码

#### 第一阶段：校验和初始化

```go
func mapassign(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
	if h == nil {
		panic(plainError("assignment to entry in nil map"))
	}
	...
	if h.flags&hashWriting != 0 {
		throw("concurrent map writes")
	}
	alg := t.key.alg
	hash := alg.hash(key, uintptr(h.hash0))

	h.flags |= hashWriting

	if h.buckets == nil {
		h.buckets = newobject(t.bucket) // newarray(t.bucket, 1)
	}
    ...
}
```

- 判断 hmap 是否已经初始化（是否为 nil）
- 判断是否并发读写 map，若是则抛出异常
- 根据 key 的不同类型调用不同的 hash 方法计算得出 hash 值
- 设置 flags 标志位，表示有一个 goroutine 正在写入数据。因为 `alg.hash` 有可能出现 `panic` 导致异常
- 判断 buckets 是否为 nil，若是则调用 `newobject` 根据当前 bucket 大小进行分配（例如：上章节提到的 `makemap_small` 方法，就在初始化时没有初始 buckets，那么它在第一次赋值时就会对 buckets 分配）

#### 第二阶段：寻找可插入位和更新既有值

```go
...
again:
	bucket := hash & bucketMask(h.B)
	if h.growing() {
		growWork(t, h, bucket)
	}
	b := (*bmap)(unsafe.Pointer(uintptr(h.buckets) + bucket*uintptr(t.bucketsize)))
	top := tophash(hash)

	var inserti *uint8
	var insertk unsafe.Pointer
	var val unsafe.Pointer
	for {
		for i := uintptr(0); i < bucketCnt; i++ {
			if b.tophash[i] != top {
				if b.tophash[i] == empty && inserti == nil {
					inserti = &b.tophash[i]
					insertk = add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
					val = add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.valuesize))
				}
				continue
			}
			k := add(unsafe.Pointer(b), dataOffset+i*uintptr(t.keysize))
			if t.indirectkey {
				k = *((*unsafe.Pointer)(k))
			}
			if !alg.equal(key, k) {
				continue
			}
			// already have a mapping for key. Update it.
			if t.needkeyupdate {
				typedmemmove(t.key, k, key)
			}
			val = add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+i*uintptr(t.valuesize))
			goto done
		}
		ovf := b.overflow(t)
		if ovf == nil {
			break
		}
		b = ovf
	}

	if !h.growing() && (overLoadFactor(h.count+1, h.B) || tooManyOverflowBuckets(h.noverflow, h.B)) {
		hashGrow(t, h)
		goto again // Growing the table invalidates everything, so try again
	}
	...
```

- 根据低八位计算得到 bucket 的内存地址，并判断是否正在扩容，若正在扩容中则先迁移再接着处理
- 计算并得到 bucket 的 bmap 指针地址，计算 key hash 高八位用于查找 Key
- 迭代 buckets 中的每一个 bucket（共 8 个），对比 `bucket.tophash` 与 top（高八位）是否一致
- 若不一致，判断是否为空槽。若是空槽（有两种情况，第一种是**没有插入过**。第二种是**插入后被删除**），则把该位置标识为可插入 tophash 位置。注意，这里就是第一个可以插入数据的地方
- 若 key 与当前 k 不匹配则跳过。但若是匹配（也就是原本已经存在），则进行更新。最后跳出并返回 value 的内存地址
- 判断是否迭代完毕，若是则结束迭代 buckets 并更新当前桶位置
- 若满足三个条件：触发最大 `LoadFactor` 、存在过多溢出桶 `overflow buckets`、没有正在进行扩容。就会进行扩容动作（以确保后续的动作）

总的来讲，这一块逻辑做了两件大事，第一是**寻找空位，将位置其记录在案，用于后续的插入动作**。第二是**判断 Key 是否已经存在哈希表中，存在则进行更新**。而若是第二种场景，更新完毕后就会进行收尾动作，第一种将继续执行下述的代码

#### 第三阶段：申请新的插入位和插入新值

```go
    ...
	if inserti == nil {
		newb := h.newoverflow(t, b)
		inserti = &newb.tophash[0]
		insertk = add(unsafe.Pointer(newb), dataOffset)
		val = add(insertk, bucketCnt*uintptr(t.keysize))
	}

	if t.indirectkey {
		kmem := newobject(t.key)
		*(*unsafe.Pointer)(insertk) = kmem
		insertk = kmem
	}
	if t.indirectvalue {
		vmem := newobject(t.elem)
		*(*unsafe.Pointer)(val) = vmem
	}
	typedmemmove(t.key, insertk, key)
	*inserti = top
	h.count++

done:
	...
	return val

```

经过前面迭代寻找动作，若没有找到可插入的位置，意味着当前的所有桶都满了，将重新分配一个新溢出桶用于插入动作。最后再在上一步申请的新插入位置，存储键值对，返回该值的内存地址

#### 第四阶段：写入

但是这里又疑惑了？最后为什么是返回内存地址。这是因为隐藏的最后一步写入动作（将值拷贝到指定内存区域）是通过底层汇编配合来完成的，在 runtime 中只完成了绝大部分的动作

```go
func main() {
	m := make(map[int32]int32)
	m[0] = 6666666
}
```

对应的汇编部分：

```
...
0x0099 00153 (test.go:6)	CALL	runtime.mapassign_fast32(SB)
0x009e 00158 (test.go:6)	PCDATA	$2, $2
0x009e 00158 (test.go:6)	MOVQ	24(SP), AX
0x00a3 00163 (test.go:6)	PCDATA	$2, $0
0x00a3 00163 (test.go:6)	MOVL	$6666666, (AX)
```

这里分为了几个部位，主要是调用 `mapassign` 函数和拿到值存放的内存地址，再将 6666666 这个值存放进该内存地址中。另外我们看到 `PCDATA` 指令，主要是包含一些垃圾回收的信息，由编译器产生

### 小结

通过前面几个阶段的分析，我们可梳理出一些要点。例如：

- 不同类型对应哈希函数不一样
- 高八位用于定位 bucket
- 低八位用于定位 key，快速试错后再进行完整对比
- buckets/overflow buckets 遍历
- 可插入位的处理
- 最终写入动作与底层汇编的交互

## 扩容

在所有动作中，扩容规则是大家较关注的点，也是赋值里非常重要的一环。因此咱们将这节拉出来，对这块细节进行研讨

### 什么时候扩容

```go
if !h.growing() && (overLoadFactor(h.count+1, h.B) || tooManyOverflowBuckets(h.noverflow, h.B)) {
	hashGrow(t, h)
	goto again
}
```

在特定条件的情况下且当前没有正在进行扩容动作（以判断 `hmap.oldbuckets != nil` 为基准）。哈希表在赋值、删除的动作下会触发扩容行为，条件如下：

- 触发 `load factor` 的最大值，负载因子已达到当前界限
- 溢出桶 `overflow buckets` 过多

### 什么时候受影响

那么什么情况下会对这两个 “值” 有影响呢？如下：

1. 负载因子 `load factor`，用途是评估哈希表当前的时间复杂度，其与哈希表当前包含的键值对数、桶数量等相关。如果负载因子越大，则说明空间使用率越高，但产生哈希冲突的可能性更高。而负载因子越小，说明空间使用率低，产生哈希冲突的可能性更低
2. 溢出桶 `overflow buckets` 的判定与 buckets 总数和 overflow buckets 总数相关联

### 因子关系

| loadFactor | %overflow | bytes/entry | hitprobe | missprobe |
| ---------- | --------- | ----------- | -------- | --------- |
| 4.00       | 2.13      | 20.77       | 3.00     | 4.00      |
| 4.50       | 4.05      | 17.30       | 3.25     | 4.50      |
| 5.00       | 6.85      | 14.77       | 3.50     | 5.00      |
| 5.50       | 10.55     | 12.94       | 3.75     | 5.50      |
| 6.00       | 15.27     | 11.67       | 4.00     | 6.00      |
| 6.50       | 20.90     | 10.79       | 4.25     | 6.50      |
| 7.00       | 27.14     | 10.15       | 4.50     | 7.00      |

- loadFactor：负载因子
- %overflow：溢出率，具有溢出桶 `overflow buckets` 的桶的百分比
- bytes/entry：每个键值对所的字节数开销
- hitprobe：查找存在的 key 时，平均需要检索的条目数量
- missprobe：查找不存在的 key 时，平均需要检索的条目数量

这一组数据能够体现出不同的负载因子会给哈希表的动作带来怎么样的影响。而在上一章节我们有提到默认的负载因子是 6.5 (loadFactorNum/loadFactorDen)，可以看出来是经过测试后取出的一个比较合理的因子。能够较好的影响哈希表的扩容动作的时机

### 源码剖析

```go
func hashGrow(t *maptype, h *hmap) {
	bigger := uint8(1)
	if !overLoadFactor(h.count+1, h.B) {
		bigger = 0
		h.flags |= sameSizeGrow
	}
	oldbuckets := h.buckets
	newbuckets, nextOverflow := makeBucketArray(t, h.B+bigger, nil)
    ...
	h.oldbuckets = oldbuckets
	h.buckets = newbuckets
	h.nevacuate = 0
	h.noverflow = 0

	if h.extra != nil && h.extra.overflow != nil {
		if h.extra.oldoverflow != nil {
			throw("oldoverflow is not nil")
		}
		h.extra.oldoverflow = h.extra.overflow
		h.extra.overflow = nil
	}
	if nextOverflow != nil {
		if h.extra == nil {
			h.extra = new(mapextra)
		}
		h.extra.nextOverflow = nextOverflow
	}

	// the actual copying of the hash table data is done incrementally
	// by growWork() and evacuate().
}
```

#### 第一阶段：确定扩容容量规则

在上小节有讲到扩容的依据有两种，在 `hashGrow` 开头就进行了划分。如下：

```go
if !overLoadFactor(h.count+1, h.B) {
	bigger = 0
	h.flags |= sameSizeGrow
}
```

若不是负载因子 `load factor` 超过当前界限，也就是属于溢出桶 `overflow buckets` 过多的情况。因此本次扩容规则将是 `sameSizeGrow`，即是**不改变大小的扩容动作**。那要是前者的情况呢？

```go
bigger := uint8(1)
...
newbuckets, nextOverflow := makeBucketArray(t, h.B+bigger, nil)
```

结合代码分析可得出，若是负载因子 `load factor` 达到当前界限，将会动态扩容**当前大小的两倍**作为其新容量大小

#### 第二阶段：初始化、交换新旧 桶/溢出桶

主要是针对扩容的相关数据**前置处理**，涉及 buckets/oldbuckets、overflow/oldoverflow 之类与存储相关的字段

```go
...
oldbuckets := h.buckets
newbuckets, nextOverflow := makeBucketArray(t, h.B+bigger, nil)

flags := h.flags &^ (iterator | oldIterator)
if h.flags&iterator != 0 {
	flags |= oldIterator
}

h.B += bigger
...
h.noverflow = 0

if h.extra != nil && h.extra.overflow != nil {
	...
	h.extra.oldoverflow = h.extra.overflow
	h.extra.overflow = nil
}
if nextOverflow != nil {
	...
	h.extra.nextOverflow = nextOverflow
}
```

这里注意到这段代码： `newbuckets, nextOverflow := makeBucketArray(t, h.B+bigger, nil)`。第一反应是扩容的时候就马上申请并初始化内存了吗？假设涉及大量的内存分配，那挺耗费性能的...

然而并不，内部只会先进行预分配，当使用的时候才会真正的去初始化

#### 第三阶段：扩容

在源码中，发现第三阶段的流转并没有显式展示。这是因为流转由底层去做控制了。但通过分析代码和注释，可得知由第三阶段涉及 `growWork` 和 `evacuate` 方法。如下：

```go
func growWork(t *maptype, h *hmap, bucket uintptr) {
	evacuate(t, h, bucket&h.oldbucketmask())

	if h.growing() {
		evacuate(t, h, h.nevacuate)
	}
}
```

在该方法中，主要是两个 `evacuate` 函数的调用。他们在调用上又分别有什么区别呢？如下：

- evacuate(t, h, bucket&h.oldbucketmask()): 将 oldbucket 中的元素迁移 rehash 到扩容后的新 bucket
- evacuate(t, h, h.nevacuate): 如果当前正在进行扩容，则再进行多一次迁移

另外，在执行扩容动作的时候，可以发现都是以 bucket/oldbucket 为单位的，而不是传统的 buckets/oldbuckets。再结合代码分析，可得知在 Go map 中**扩容是采取增量扩容的方式，并非一步到位**

##### 为什么是增量扩容？

如果是全量扩容的话，那问题就来了。假设当前 hmap 的容量比较大，直接全量扩容的话，就会导致扩容要花费大量的时间和内存，导致系统卡顿，最直观的表现就是慢。显然，不能这么做

而增量扩容，就可以解决这个问题。它通过每一次的 map 操作行为去分摊总的一次性动作。因此有了 buckets/oldbuckets 的设计，它是逐步完成的，并且会在扩容完毕后才进行清空

### 小结

通过前面三个阶段的分析，可以得知扩容的大致过程。我们阶段性总结一下。主要如下：

- 根据需扩容的原因不同（overLoadFactor/tooManyOverflowBuckets），分为两类容量规则方向，为等量扩容（不改变原有大小）或双倍扩容
- 新申请的扩容空间（newbuckets/newoverflow）都是预分配，等真正使用的时候才会初始化
- 扩容完毕后（预分配），不会马上就进行迁移。而是采取**增量扩容**的方式，当有访问到具体 bukcet 时，才会逐渐的进行迁移（将 oldbucket 迁移到 bucket）

这时候又想到，既然迁移是逐步进行的。那如果在途中又要扩容了，怎么办？

```go
again:
	bucket := hash & bucketMask(h.B)
    ...
	if !h.growing() && (overLoadFactor(h.count+1, h.B) || tooManyOverflowBuckets(h.noverflow, h.B)) {
		hashGrow(t, h)
		goto again
	}
```

在这里注意到 `goto again` 语句，结合上下文可得若正在进行扩容，就会不断地进行迁移。待迁移完毕后才会开始进行下一次的扩容动作

## 迁移

在扩容的完整闭环中，包含着迁移的动作，又称 “搬迁”。因此我们继续深入研究 `evacuate` 函数。接下来一起打开迁移世界的大门。如下：

```go
type evacDst struct {
	b *bmap
	i int
	k unsafe.Pointer
	v unsafe.Pointer
}
```

`evacDst` 是迁移中的基础数据结构，其包含如下字段：

- b: 当前目标桶
- i: 当前目标桶存储的键值对数量
- k: 指向当前 key 的内存地址
- v: 指向当前 value 的内存地址

```go
func evacuate(t *maptype, h *hmap, oldbucket uintptr) {
	b := (*bmap)(add(h.oldbuckets, oldbucket*uintptr(t.bucketsize)))
	newbit := h.noldbuckets()
	if !evacuated(b) {
		var xy [2]evacDst
		x := &xy[0]
		x.b = (*bmap)(add(h.buckets, oldbucket*uintptr(t.bucketsize)))
		x.k = add(unsafe.Pointer(x.b), dataOffset)
		x.v = add(x.k, bucketCnt*uintptr(t.keysize))

		if !h.sameSizeGrow() {
			y := &xy[1]
			y.b = (*bmap)(add(h.buckets, (oldbucket+newbit)*uintptr(t.bucketsize)))
			y.k = add(unsafe.Pointer(y.b), dataOffset)
			y.v = add(y.k, bucketCnt*uintptr(t.keysize))
		}

		for ; b != nil; b = b.overflow(t) {
            ...
		}

		if h.flags&oldIterator == 0 && t.bucket.kind&kindNoPointers == 0 {
			b := add(h.oldbuckets, oldbucket*uintptr(t.bucketsize))
			ptr := add(b, dataOffset)
			n := uintptr(t.bucketsize) - dataOffset
			memclrHasPointers(ptr, n)
		}
	}

	if oldbucket == h.nevacuate {
		advanceEvacuationMark(h, t, newbit)
	}
}
```

- 计算并得到 oldbucket 的 bmap 指针地址
- 计算 hmap 在增长之前的桶数量
- 判断当前的迁移（搬迁）状态，以便流转后续的操作。若没有正在进行迁移 `!evacuated(b)` ，则根据扩容的规则的不同，当规则为等量扩容 `sameSizeGrow` 时，只使用一个 `evacDst` 桶用于分流。而为双倍扩容时，就会使用两个 `evacDst` 进行分流操作
- 当分流完毕后，需要迁移的数据都会通过 `typedmemmove` 函数迁移到指定的目标桶上
- 若当前不存在 flags 使用标志、使用 oldbucket 迭代器、bucket 不为指针类型。则取消链接溢出桶、清除键值
- 在最后 `advanceEvacuationMark` 函数中会对迁移进度 `hmap.nevacuate` 进行累积计数，并调用 `bucketEvacuated` 对旧桶 oldbuckets 进行不断的迁移。直至全部迁移完毕。那么也就表示扩容完毕了，会对 `hmap.oldbuckets` 和 `h.extra.oldoverflow` 进行清空

总的来讲，就是计算得到所需数据的位置。再根据当前的迁移状态、扩容规则进行数据分流迁移。结束后进行清理，促进 GC 的回收

## 总结

在本章节我们主要研讨了 Go map 的几个核心动作，分别是：“赋值、扩容、迁移” 。而通过本次的阅读，我们能够更进一步的认识到一些要点，例如：

- 赋值的时候会触发扩容吗？
- 负载因子是什么？过高会带来什么问题？它的变动会对哈希表操作带来什么影响吗？
- 溢出桶越多会带来什么问题？
- 是否要扩容的基准条件是什么？
- 扩容的容量规则是怎么样的？
- 扩容的步骤是怎么样的？涉及到了哪些数据结构？
- 扩容是一次性扩容还是增量扩容？
- 正在扩容的时候又要扩容怎么办？
- 扩容时的迁移分流动作是怎么样的？
- 在扩容动作中，底层汇编承担了什么角色？做了什么事？
- 在 buckets/overflow buckets 中寻找时，是如何 “快速” 定位值的？低八位、高八位的用途？
- 空槽有可能出现在任意位置吗？假设已经没有空槽了，但是又有新值要插入，底层会怎么处理

最后希望你通过本文的阅读，能更清楚地了解到 Go map 是怎么样运作的 ：）


================================================
FILE: content/posts/go/map/2019-04-07-why-map-no-order.md
================================================
---

title:      "为什么遍历 Go map 是无序的"
date:       2019-04-07 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

![image](http://wx2.sinaimg.cn/large/006fVPCvly1g1s1ah84k8j30k70dvaac.jpg)

有的小伙伴没留意过 Go map 输出顺序，以为它是稳定的有序的；有的小伙伴知道是无序的，但却不知道为什么？有的却理解错误？今天我们将通过本文，揭开 `for range map` 的 “神秘” 面纱，看看它内部实现到底是怎么样的，输出顺序到底是怎么样？

## 前言

```go
func main() {
	m := make(map[int32]string)
	m[0] = "EDDYCJY1"
	m[1] = "EDDYCJY2"
	m[2] = "EDDYCJY3"
	m[3] = "EDDYCJY4"
	m[4] = "EDDYCJY5"

	for k, v := range m {
		log.Printf("k: %v, v: %v", k, v)
	}
}
```

假设运行这段代码，输出结果是按顺序？还是无序输出呢？

```
2019/04/03 23:27:29 k: 3, v: EDDYCJY4
2019/04/03 23:27:29 k: 4, v: EDDYCJY5
2019/04/03 23:27:29 k: 0, v: EDDYCJY1
2019/04/03 23:27:29 k: 1, v: EDDYCJY2
2019/04/03 23:27:29 k: 2, v: EDDYCJY3
```

从输出结果上来讲，是非固定顺序输出的，也就是每次都不一样（标题也讲了）。但这是为什么呢？

首先**建议你先自己想想原因**。其次我在面试时听过一些说法。有人说因为是哈希的所以就是无（乱）序等等说法。当时我是有点 ？？？

这也是这篇文章出现的原因，希望大家可以一起研讨一下，理清这个问题 ：）

## 看一下汇编

```
    ...
	0x009b 00155 (main.go:11)	LEAQ	type.map[int32]string(SB), AX
	0x00a2 00162 (main.go:11)	PCDATA	$2, $0
	0x00a2 00162 (main.go:11)	MOVQ	AX, (SP)
	0x00a6 00166 (main.go:11)	PCDATA	$2, $2
	0x00a6 00166 (main.go:11)	LEAQ	""..autotmp_3+24(SP), AX
	0x00ab 00171 (main.go:11)	PCDATA	$2, $0
	0x00ab 00171 (main.go:11)	MOVQ	AX, 8(SP)
	0x00b0 00176 (main.go:11)	PCDATA	$2, $2
	0x00b0 00176 (main.go:11)	LEAQ	""..autotmp_2+72(SP), AX
	0x00b5 00181 (main.go:11)	PCDATA	$2, $0
	0x00b5 00181 (main.go:11)	MOVQ	AX, 16(SP)
	0x00ba 00186 (main.go:11)	CALL	runtime.mapiterinit(SB)
	0x00bf 00191 (main.go:11)	JMP	207
	0x00c1 00193 (main.go:11)	PCDATA	$2, $2
	0x00c1 00193 (main.go:11)	LEAQ	""..autotmp_2+72(SP), AX
	0x00c6 00198 (main.go:11)	PCDATA	$2, $0
	0x00c6 00198 (main.go:11)	MOVQ	AX, (SP)
	0x00ca 00202 (main.go:11)	CALL	runtime.mapiternext(SB)
	0x00cf 00207 (main.go:11)	CMPQ	""..autotmp_2+72(SP), $0
	0x00d5 00213 (main.go:11)	JNE	193
	...
```

我们大致看一下整体过程，重点处理 Go map 循环迭代的是两个 runtime 方法，如下：

- runtime.mapiterinit
- runtime.mapiternext

但你可能会想，明明用的是 `for range` 进行循环迭代，怎么出现了这两个函数，怎么回事？

## 看一下转换后

```go
var hiter map_iteration_struct
for mapiterinit(type, range, &hiter); hiter.key != nil; mapiternext(&hiter) {
    index_temp = *hiter.key
    value_temp = *hiter.val
    index = index_temp
    value = value_temp
    original body
}
```

实际上编译器对于 slice 和 map 的循环迭代有不同的实现方式，并不是 `for` 一扔就完事了，还做了一些附加动作进行处理。而上述代码就是 `for range map` 在编译器展开后的伪实现

## 看一下源码

### runtime.mapiterinit

```go
func mapiterinit(t *maptype, h *hmap, it *hiter) {
	...
	it.t = t
	it.h = h
	it.B = h.B
	it.buckets = h.buckets
	if t.bucket.kind&kindNoPointers != 0 {
		h.createOverflow()
		it.overflow = h.extra.overflow
		it.oldoverflow = h.extra.oldoverflow
	}

	r := uintptr(fastrand())
	if h.B > 31-bucketCntBits {
		r += uintptr(fastrand()) << 31
	}
	it.startBucket = r & bucketMask(h.B)
	it.offset = uint8(r >> h.B & (bucketCnt - 1))
	it.bucket = it.startBucket
    ...

	mapiternext(it)
}
```

通过对 `mapiterinit` 方法阅读，可得知其主要用途是在 map 进行遍历迭代时**进行初始化动作**。共有三个形参，用于读取当前哈希表的类型信息、当前哈希表的存储信息和当前遍历迭代的数据

#### 为什么

咱们关注到源码中 `fastrand` 的部分，这个方法名，是不是迷之眼熟。没错，它是一个生成随机数的方法。再看看上下文：

```go
...
// decide where to start
r := uintptr(fastrand())
if h.B > 31-bucketCntBits {
	r += uintptr(fastrand()) << 31
}
it.startBucket = r & bucketMask(h.B)
it.offset = uint8(r >> h.B & (bucketCnt - 1))

// iterator state
it.bucket = it.startBucket
```

在这段代码中，它生成了随机数。用于决定从哪里开始循环迭代。更具体的话就是根据随机数，选择一个桶位置作为起始点进行遍历迭代

因此每次重新 `for range map`，你见到的结果都是不一样的。那是因为它的起始位置根本就不固定！

### runtime.mapiternext

```go
func mapiternext(it *hiter) {
    ...
    for ; i < bucketCnt; i++ {
		...
		k := add(unsafe.Pointer(b), dataOffset+uintptr(offi)*uintptr(t.keysize))
		v := add(unsafe.Pointer(b), dataOffset+bucketCnt*uintptr(t.keysize)+uintptr(offi)*uintptr(t.valuesize))
		...
		if (b.tophash[offi] != evacuatedX && b.tophash[offi] != evacuatedY) ||
			!(t.reflexivekey || alg.equal(k, k)) {
			...
			it.key = k
			it.value = v
		} else {
			rk, rv := mapaccessK(t, h, k)
			if rk == nil {
				continue // key has been deleted
			}
			it.key = rk
			it.value = rv
		}
		it.bucket = bucket
		if it.bptr != b {
			it.bptr = b
		}
		it.i = i + 1
		it.checkBucket = checkBucket
		return
	}
	b = b.overflow(t)
	i = 0
	goto next
}
```

在上小节中，咱们已经选定了起始桶的位置。接下来就是通过 `mapiternext` 进行**具体的循环遍历动作**。该方法主要涉及如下：

- 从已选定的桶中开始进行遍历，寻找桶中的下一个元素进行处理
- 如果桶已经遍历完，则对溢出桶 `overflow buckets` 进行遍历处理

通过对本方法的阅读，可得知其对 buckets 的**遍历规则**以及对于扩容的一些处理（这不是本文重点。因此没有具体展开）

## 总结

在本文开始，咱们先提出核心讨论点：“为什么 Go map 遍历输出是不固定顺序？”。而通过这一番分析，原因也很简单明了。就是 `for range map` 在开始处理循环逻辑的时候，就做了随机播种...

你想问为什么要这么做？当然是官方有意为之，因为 Go 在早期（1.0）的时候，虽是稳定迭代的，但从结果来讲，其实是无法保证每个 Go 版本迭代遍历规则都是一样的。而这将会导致可移植性问题。因此，改之。也请不要依赖...

## 参考

- [Go maps in action](https://blog.golang.org/go-maps-in-action)


================================================
FILE: content/posts/go/map-65.md
================================================
---
title: "面试官：为什么 Go 的负载因子是 6.5？"
date: 2021-12-31T12:55:07+08:00
toc: true
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

最近我有一个朋友，在网上看到一个有趣的段子，引发了我一些兴趣。

如下图：

![](https://files.mdnice.com/user/3610/e81547d8-8de7-4310-a62f-e59ce4c0def2.png)

听说是在最后的闲聊、吹水、聊人生、乱扯环节了，不是在技术环节了，所以大家也不用太在意什么技术评估法则（别杠）。

煎鱼作为一名技术号主，看到这里的 6.5，就想给大家挖一挖，这到底是何物，和大家一同学习和增长知识！

## 6.5 是什么

实际上在 Go 语言中，就存在 6.5 这一概念，与 map 存在直接关系，因此我们需要先了解 map 的基本数据结构，再介绍 6.5 的背景和由来。

开始学习 6.5 吧！

### 了解 map 底层

我以前在写《[深入理解 Go map：初始化和访问元素](https://eddycjy.com/posts/go/map/2019-03-05-map-access/)》时有介绍过 map 的基础数据结构。

基本结构如下图：

![map 基本数据结构](https://files.mdnice.com/user/3610/8679a84f-0d21-485d-b55f-dc9d70d5ddd1.png)

其中重要的一个基本单位是 hmap：

```golang
type hmap struct {
	count     int
	flags     uint8
	B         uint8
	noverflow uint16
	hash0     uint32
	buckets    unsafe.Pointer
	oldbuckets unsafe.Pointer
	nevacuate  uintptr
	extra *mapextra
}

type mapextra struct {
	overflow    *[]*bmap
	oldoverflow *[]*bmap
	nextOverflow *bmap
}
```

- count：map 的大小，也就是 len() 的值，代指 map 中的键值对个数。
- flags：状态标识，主要是 goroutine 写入和扩容机制的相关状态控制。并发读写的判断条件之一就是该值。
- B：**桶，最大可容纳的元素数量，值为 负载因子（默认 6.5） * 2 ^ B，是 2 的指数**。
- noverflow：溢出桶的数量。
- hash0：哈希因子。
- buckets：保存当前桶数据的指针地址（指向一段连续的内存地址，主要存储键值对数据）。
- oldbuckets，保存旧桶的指针地址。
- nevacuate：迁移进度。
- extra：原有 buckets 满载后，会发生扩容动作，在 Go 的机制中使用了增量扩容，如下为细项：
    - overflow 为 hmap.buckets （当前）溢出桶的指针地址。
    - oldoverflow 为 hmap.oldbuckets （旧）溢出桶的指针地址。
    - nextOverflow 为空闲溢出桶的指针地址。

我们关注到 hmap 的 B 字段，其值就是 6.5，他就是我们在苦苦寻找的 6.5，但他又是什么呢？

### 什么是负载因子

B 值，这里就涉及到一个概念：**负载因子（load factor），用于衡量当前哈希表中空间占用率的核心指标**，也就是每个 bucket 桶存储的平均元素个数。

另外负载因子**与扩容、迁移**等重新散列（rehash）行为有直接关系：
- 在程序运行时，会不断地进行插入、删除等，会导致 bucket 不均，内存利用率低，需要迁移。
- 在程序运行时，出现负载因子过大，需要做扩容，解决 bucket 过大的问题。

负载因子是哈希表中的一个重要指标，在各种版本的哈希表实现中都有类似的东西，主要目的是**为了平衡 buckets 的存储空间大小和查找元素时的性能高低**。

在接触各种哈希表时都可以关注一下，做不同的对比，看看各家的考量。

## 为什么是 6.5

了解是什么后，我们进一步深挖。

为什么 Go 语言中哈希表的负载因子是 6.5，为什么不是 8 ，也不是 1。这里面有可靠的数据支撑吗？

### 测试报告

实际上这是 Go 官方的经过认真的测试得出的数字，一起来看看官方的这份测试报告。

报告中共包含 4 个关键指标，如下：

| loadFactor | %overflow  |  bytes/entry | hitprobe |    missprobe |
| --- | --- | --- | --- | --- |
|  4.00   |  2.13   |  20.77   |  3.00   |  4.00   |
|  4.50   |  4.05  |  17.30   |  3.25   |  4.50   |
|  5.00   |  6.85   | 14.77    | 3.50    |  5.00   |
|  5.50   |  10.55    | 12.94    | 3.75    | 5.50    |
|  6.00   |  15.27   | 11.67    | 4.00    | 6.00    |
|  6.50   |  20.90   | 10.79    | 4.25    | 6.50    |
|  7.00   |  27.14   | 10.15    | 4.50    | 7.00    |
|  7.50   |  34.03   | 9.73    | 4.75    | 7.50    |
|  8.00   |  41.10   | 9.40    |  5.00   | 8.00    |

- loadFactor：负载因子，也有叫装载因子。
- %overflow：溢出率，有溢出 bukcet 的百分比。
- bytes/entry：每对 key/elem 的开销字节数.
- hitprobe：查找一个存在的 key 时，要查找的平均个数。
- missprobe：查找一个不存在的 key 时，要查找的平均个数。

### 选择数值

结合测试报告一看，好家伙，不测不知道，一测吓一跳，有依据了。

Go 官方发现：**负载因子太大了，会有很多溢出的桶。太小了，就会浪费很多空间**（too large and we have lots of overflow buckets, too small and we waste a lot of space）。

![来自 Go 官方源码说明](https://files.mdnice.com/user/3610/93b87f8d-a0ad-4503-b4f9-e3cf040468df.png)

根据这份测试结果和讨论，Go 官方把 Go 中的 map 的负载因子硬编码为 6.5，这就是 6.5 的选择缘由。

这意味着在 Go 语言中，**当 B（bucket）平均每个存储的元素大于或等于 6.5 时，就会触发扩容行为**，这是作为我们用户对这个数值最近的接触。

## 总结

在今天这篇文章中，我们先快速了解了 Go 语言中 map 的基本数据结构和设计，这和我们要解释的问题紧密相关。

紧接着针对开头所提出的 6.5，进行了介绍和说明，这其实是 map 中的负载因子。其数值的确定来源于 Go 官方的测试。

为什么是 6.5，你懂了吗？

## 参考
- [src/runtime/map.go](https://golang.org/src/runtime/map.go)
- [深度解析golang map](https://juejin.cn/post/6954707500151078919)
- [golang中map底层B值的计算逻辑](https://zhuanlan.zhihu.com/p/366472077)

================================================
FILE: content/posts/go/map-con.md
================================================
---
title: "Go 为什么不在语言层面支持 map 并发？"
date: 2022-02-05T15:55:22+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

很多小伙伴学习 Go 语言的语法时，可能只是轻轻地看到过这个问题，结果一旦上手，多多少少一个组内总会碰到过几次。

甚至会发现有一定年限的程序员也会遇到。有小伙伴疑惑了，这么折腾，为什么 Go 不直接在语言层面就支持 map 并发，那得有多香？

## 为什么原生不支持

凭什么 Go 官方还不支持，难不成太复杂了，性能太差了，到底是为什么？

官方答复原因如下（via @go faq）：

- 典型使用场景：map 的典型使用场景是不需要从多个 goroutine 中进行安全访问。
- 非典型场景（需要原子操作）：map 可能是一些更大的数据结构或已经同步的计算的一部分。
- 性能场景考虑：若是只是为少数程序增加安全性，导致 map 所有的操作都要处理 mutex，将会降低大多数程序的性能。

核心来讲就是：Go 团队在经过了长时间的讨论后，认为原生 map 更应适配典型使用场景。

如果为了小部分情况，将**会导致大部分程序付出性能代价**，决定了不支持原生的并发 map 读写。且在 Go1.6 起，**增加了检测机制**，并发的话会导致异常。

## 为什么要崩溃

前面有提到一点，在 Go1.6 起会进行原生 map 的并发检测，这是一些人的 “噩梦”。

在此有人吐槽到：“明明给我抛个错就好了，凭什么要让我的 Go 进程直接崩溃掉，分分钟给我背个 P0”。

### 场景枚举

这里我们假设一下，如果并发读写 map 是以下两种场景：

1. 产生 panic：程序 panic -> 默认走进 recover -> 没有对并发 map 进行处理 -> map 存在脏数据 -> 程序使用脏数据 -> 产生**未知((影响。
2. 产生 crash：程序 crash -> 直接崩溃 -> 保全数据（数据正常）-> 产生**明确((风险。

你会选择哪一种方案呢？Go 官方在两者的风险衡量中选择了第二种。

无论是编程，还是人生。如何在随机性中掌握确定性的部分，也是一门极大的哲学了。

### let it crash

Go 官方团队选择的方式是业内经典的 “let it crash” 行为，很多编程语言中，都会将其奉行为设计哲学。

**let it crash 是指工程师不必过分担心未知的错误，而去进行面面俱到的防御性编码**。

这块理念最经典的就是 erlang 了。

## 总结

在今天这篇文章中，我们介绍了 Go 语言为什么不支持原生支持 map 并发，核心原因是大部分场景都不需要，从性能考虑上做的考虑。

直接让并发读写 map 的原因，是从 “let it crash” 去考虑。这块如果你想在自己的工程中避免这个情况，可以在 linter 等工具链加入竞态检测（-race），也可以避免这类风险。

你觉得 Go 这块的设计考虑怎么样呢？欢迎在评论区留言和交流：）

================================================
FILE: content/posts/go/map-reset.md
================================================
---
title: "Go map 如何缩容？"
date: 2021-12-31T12:55:07+08:00
toc: true
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天看到 Go 圈子的著名股神（不是我...），在归类中简单的提到了 Go 语言中 map 的缩容的描述，这让我对其产生了兴趣，想要来一探究竟。

我们常常喊扩缩容，扩缩容，但社区里都是清一色分析扩容机制，Go 面试官也都是卷 Go 语言 map 的扩容机制...

在 **Go 语言中的 map 缩容机制是怎么做的**呢，今天就由煎鱼带大家一起研讨围观一轮。

## 基本分析

在 Go 底层源码 src/runtime/map.go 中，扩缩容的处理方法是 grow 为前缀的方法来处理的。

其中扩缩容涉及到的是插入元素的操作，对应 mapassign 方法：

```golang
func mapassign(t *maptype, h *hmap, key unsafe.Pointer) unsafe.Pointer {
  ...
	if !h.growing() && (overLoadFactor(h.count+1, h.B) || tooManyOverflowBuckets(h.noverflow, h.B)) {
		hashGrow(t, h)
		goto again
	}
  ...
}

func (h *hmap) growing() bool {
	return h.oldbuckets != nil
}

func overLoadFactor(count int, B uint8) bool {
	return count > bucketCnt && uintptr(count) > loadFactorNum*(bucketShift(B)/loadFactorDen)
}

func tooManyOverflowBuckets(noverflow uint16, B uint8) bool {
	if B > 15 {
		B = 15
	}
  
	return noverflow >= uint16(1)<<(B&15)
}
```

核心看到针对扩缩容的判断逻辑：
- 当前没有在扩容：条件为 oldbuckets 不为 nil。
- 是否可以进行扩容：条件为 `hmap.count`> hash 桶数量 `(2^B)*6.5`。其中 `hmap.count` 指的是map 的数据数目， `2^B` 仅指 hash 数组的大小，不包含溢出桶。
- 是否可以进行缩容：条件为溢出桶（noverflow）的数量 >= 32768（1<<15）。

而我们可以关注到，无论是扩容还是缩容，其都是由 `hashGrow` 方法进行处理：

```golang
func hashGrow(t *maptype, h *hmap) {
	bigger := uint8(1)
	if !overLoadFactor(h.count+1, h.B) {
		bigger = 0
		h.flags |= sameSizeGrow
	}
  ...
}
```

若是扩容，则 bigger 为 1，也就是 B+1。代表 hash 表容量扩大 1 倍。不满足就是缩容，也就是 hash 表容量不变。

可以得出结论：map 的**扩缩容的主要区别在于 hmap.B 的容量大小改变**。而缩容由于 hmap.B 压根没变，内存空间的占用也是没有变化的。

## 带来的隐患

这种方式其实是存在运行隐患的，也就是**导致在删除元素时，并不会释放内存，使得分配的总内存不断增加**。如果一个不小心，拿 map 来做大 key/value 的存储，也不注意管理，很容易就内存爆了。

也就是 Go 语言的 map 目前实现的是 ”伪缩容“，仅针对溢出桶过多的情况。若是触发缩容，hash 数组的占用的内存大小不变。

若要实现 ”真缩容“，Go Contributor @josharian 表示目前**唯一可用的解决方法是：创建一个新的 map 并从旧的 map 中复制元素**。

示例如下：

```golang
old := make(map[int]int, 9999999)
new := make(map[int]int, len(old))
for k, v := range old {
    new[k] = v
}
old = new
...
```

无比的像，复制粘贴，大的往小的挪动，再删掉大的就可以了。

果然程序员的解决方案都是相似的。

## 为什么不支持

下述内容会主要基于如下两个 issues 和 proposal 来分析：
1. 《[runtime: shrink map as elements are deleted](https://github.com/golang/go/issues/20135 "runtime: shrink map as elements are deleted")》
2. 《[proposal: runtime: add way to clear and reuse a map's working storage](https://github.com/golang/go/issues/45328 "proposal: runtime: add way to clear and reuse a map's working storage")》

目前 map 的缩容处理起来比较棘手，最早的 issues 是 2016 年提出的，也有人提过一些提案，但都因为种种原因被拒绝了。

简单来讲，就是没有找到一个很好的方法实现，存在明确的实现成本问题，没法很方便的 ”告诉“ Go 运行时，我要：
1. 记得保留存储空间，我要立即重用 map。
2. 赶紧释放存储空间，map 从现在开始会小很多。

抽象来看症结是：**需要保证增长结果在下一个开始之前完成**，此处的增长指的是 ”从小到大，从一个大小到相同大小，从大到小“ 的复杂过程。

这属于一个多重 case，从而导致也就一直拖着，慢慢想。

## 总结

Go 语言中 map 的扩容机制是大家经常思考和学习的，但是缩容方面现在也是一个大 ”坑“。虽然不误用就没问题。

但是一旦新同学来了，不知道，一塞，就会出问题。我有一个朋友，之前面试时，就听闻有人会塞几个 GB 的数据进 map，可想而知还是很危险的。

现有 map 的缩容机制，是存在短板的，背后有着比较多重的纠结，不知道你**有没有什么好的建议或想法呢，欢迎大家一起来讨论**！

================================================
FILE: content/posts/go/map-slice-concurrency.md
================================================
---
title: "为什么 Go map 和 slice 是非线程安全的？"
date: 2021-12-31T12:54:49+08:00
toc: true
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

初入 Go 语言的大门，有不少的小伙伴会快速的 3 天精通 Go，5 天上手项目，14 天上线业务迭代，21 天排查、定位问题，顺带捎个反省报告。

其中最常见的初级错误，Go 面试较最爱问的问题之一：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/8d1a0506617a4729abe35927d87508d0~tplv-k3u1fbpfcp-zoom-1.image)
（来自读者提问）

为什么在 Go 语言里，map 和 slice 不支持并发读写，也就是是非线程安全的，为什么不支持？

见招拆招后，紧接着就会开始讨论如何让他们俩 ”冤家“ 支持并发读写？

今天我们这篇文章就来理一理，了解其前因后果，一起吸鱼学懂 Go 语言。

非线程安全的例子
--------

### slice

我们使用多个 goroutine 对类型为 slice 的变量进行操作，看看结果会变的怎么样。

如下：

```
func main() {
 var s []string
 for i := 0; i < 9999; i++ {
  go func() {
   s = append(s, "脑子进煎鱼了")
  }()
 }

 fmt.Printf("进了 %d 只煎鱼", len(s))
}

```

输出结果：

```
// 第一次执行
进了 5790 只煎鱼
// 第二次执行
进了 7370 只煎鱼
// 第三次执行
进了 6792 只煎鱼

```

你会发现无论你执行多少次，每次输出的值大概率都不会一样。也就是追加进 slice 的值，出现了覆盖的情况。

因此在循环中所追加的数量，与最终的值并不相等。且这种情况，是不会报错的，是一个出现率不算高的隐式问题。

这个产生的主要原因是程序逻辑本身就有问题，同时读取到相同索引位，自然也就会产生覆盖的写入了。

### map

同样针对 map 也如法炮制一下。重复针对类型为 map 的变量进行写入。

如下：

```
func main() {
 s := make(map[string]string)
 for i := 0; i < 99; i++ {
  go func() {
   s["煎鱼"] = "吸鱼"
  }()
 }

 fmt.Printf("进了 %d 只煎鱼", len(s))
}

```

输出结果：

```
fatal error: concurrent map writes

goroutine 18 [running]:
runtime.throw(0x10cb861, 0x15)
        /usr/local/Cellar/go/1.16.2/libexec/src/runtime/panic.go:1117 +0x72 fp=0xc00002e738 sp=0xc00002e708 pc=0x1032472
runtime.mapassign_faststr(0x10b3360, 0xc0000a2180, 0x10c91da, 0x6, 0x0)
        /usr/local/Cellar/go/1.16.2/libexec/src/runtime/map_faststr.go:211 +0x3f1 fp=0xc00002e7a0 sp=0xc00002e738 pc=0x1011a71
main.main.func1(0xc0000a2180)
        /Users/eddycjy/go-application/awesomeProject/main.go:9 +0x4c fp=0xc00002e7d8 sp=0xc00002e7a0 pc=0x10a474c
runtime.goexit()
        /usr/local/Cellar/go/1.16.2/libexec/src/runtime/asm_amd64.s:1371 +0x1 fp=0xc00002e7e0 sp=0xc00002e7d8 pc=0x1063fe1
created by main.main
        /Users/eddycjy/go-application/awesomeProject/main.go:8 +0x55

```

好家伙，程序运行会直接报错。并且是 Go 源码调用 `throw` 方法所导致的致命错误，也就是说 Go 进程会中断。

不得不说，这个并发写 map 导致的 `fatal error: concurrent map writes` 错误提示。我有一个朋友，已经看过少说几十次了，不同组，不同人...

是个日经的隐式问题。

如何支持并发读写
--------

### 对 map 上锁

实际上我们仍然存在并发读写 map 的诉求（程序逻辑决定），因为 Go 语言中的 goroutine 实在是太方便了。

像是一般写爬虫任务时，基本会用到多个 goroutine，获取到数据后再写入到 map 或者 slice 中去。

Go 官方在 Go maps in action 中提供了一种简单又便利的方式来实现：

```
var counter = struct{
    sync.RWMutex
    m map[string]int
}{m: make(map[string]int)}

```

这条语句声明了一个变量，它是一个匿名结构（struct）体，包含一个原生和一个嵌入读写锁 `sync.RWMutex`。

要想从变量中中读出数据，则调用读锁：

```
counter.RLock()
n := counter.m["煎鱼"]
counter.RUnlock()
fmt.Println("煎鱼:", n)

```

要往变量中写数据，则调用写锁：

```
counter.Lock()
counter.m["煎鱼"]++
counter.Unlock()

```

这就是一个最常见的 Map 支持并发读写的方式了。

### sync.Map

#### 前言

虽然有了 Map+Mutex 的极简方案，但是也仍然存在一定问题。那就是在 map 的数据量非常大时，只有一把锁（Mutex）就非常可怕了，一把锁会导致大量的争夺锁，导致各种冲突和性能低下。

常见的解决方案是分片化，将一个大 map 分成多个区间，各区间使用多个锁，这样子锁的粒度就大大降低了。不过该方案实现起来很复杂，很容易出错。因此 Go 团队到比较为止暂无推荐，而是采取了其他方案。

该方案就是在 Go1.9 起支持的 `sync.Map`，其支持并发读写 map，起到一个补充的作用。

#### 具体介绍

Go 语言的 `sync.Map` 支持并发读写 map，采取了 “空间换时间” 的机制，冗余了两个数据结构，分别是：read 和 dirty，减少加锁对性能的影响：

```
type Map struct {
 mu Mutex
 read atomic.Value // readOnly
 dirty map[interface{}]*entry
 misses int
}

```

其是专门为 `append-only` 场景设计的，也就是适合读多写少的场景。这是他的优点之一。

若出现写多/并发多的场景，会导致 read map 缓存失效，需要加锁，冲突变多，性能急剧下降。这是他的重大缺点。

提供了以下常用方法：

```
func (m *Map) Delete(key interface{})
func (m *Map) Load(key interface{}) (value interface{}, ok bool)
func (m *Map) LoadAndDelete(key interface{}) (value interface{}, loaded bool)
func (m *Map) LoadOrStore(key, value interface{}) (actual interface{}, loaded bool)
func (m *Map) Range(f func(key, value interface{}) bool)
func (m *Map) Store(key, value interface{})

```

*   Delete：删除某一个键的值。
    
*   Load：返回存储在 map 中的键的值，如果没有值，则返回 nil。ok 结果表示是否在 map 中找到了值。
    
*   LoadAndDelete：删除一个键的值，如果有的话返回之前的值。
    
*   LoadOrStore：如果存在的话，则返回键的现有值。否则，它存储并返回给定的值。如果值被加载，加载的结果为 true，如果被存储，则为 false。
    
*   Range：递归调用，对 map 中存在的每个键和值依次调用闭包函数 `f`。如果 `f` 返回 false 就停止迭代。
    
*   Store：存储并设置一个键的值。
    

实际运行例子如下：

```
var m sync.Map

func main() {
 //写入
 data := []string{"煎鱼", "咸鱼", "烤鱼", "蒸鱼"}
 for i := 0; i < 4; i++ {
  go func(i int) {
   m.Store(i, data[i])
  }(i)
 }
 time.Sleep(time.Second)

 //读取
 v, ok := m.Load(0)
 fmt.Printf("Load: %v, %v\n", v, ok)

 //删除
 m.Delete(1)

 //读或写
 v, ok = m.LoadOrStore(1, "吸鱼")
 fmt.Printf("LoadOrStore: %v, %v\n", v, ok)

 //遍历
 m.Range(func(key, value interface{}) bool {
  fmt.Printf("Range: %v, %v\n", key, value)
  return true
 })
}

```

输出结果：

```
Load: 煎鱼, true
LoadOrStore: 吸鱼, false
Range: 0, 煎鱼
Range: 1, 吸鱼
Range: 3, 蒸鱼
Range: 2, 烤鱼

```

为什么不支持
------

Go Slice 的话，主要还是索引位覆写问题，这个就不需要纠结了，势必是程序逻辑在编写上有明显缺陷，自行改之就好。

但 Go map 就不大一样了，很多人以为是默认支持的，一个不小心就翻车，这么的常见。那凭什么 Go 官方还不支持，难不成太复杂了，性能太差了，到底是为什么？

原因如下（via @go faq）：

*   典型使用场景：map 的典型使用场景是不需要从多个 goroutine 中进行安全访问。
    
*   非典型场景（需要原子操作）：map 可能是一些更大的数据结构或已经同步的计算的一部分。
    
*   性能场景考虑：若是只是为少数程序增加安全性，导致 map 所有的操作都要处理 mutex，将会降低大多数程序的性能。
    

汇总来讲，就是 Go 官方在经过了长时间的讨论后，认为 Go map 更应适配典型使用场景，而不是为了小部分情况，导致大部分程序付出代价（性能），决定了不支持。


## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，欢迎 Star 催更。


总结
--

在今天这篇文章中，我们针对 Go 语言中的 map 和 slice 进行了基本的介绍，也对不支持并发读者的场景进行了模拟展示。

同时也针对业内常见的支持并发读写的方式进行了讲述，最后分析了不支持的原因，让我们对整个前因后果有了一个完整的了解。

不知道你**在日常是否有遇到过 Go 语言中非线性安全的问题呢，欢迎你在评论区留言和大家一起交流**！



================================================
FILE: content/posts/go/memory-model.md
================================================
---
title: "Go 内存模型：happens-before 原则"
date: 2021-12-31T12:54:54+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在日常工作中，如果我们能够了解 Go 语言内存模型，那会带来非常大的作用。这样在看一些极端情况，又或是变态面试题的时候，就能够明白程序运行表现下的很多根本原因了。

当然，靠一篇普通文章讲完 Go 内存模型，不可能。因此今天这篇文章，把重点划在给大家**讲解 Go 语言的 happens-before 原则**这 1 个细节。

开吸，和煎鱼揭开他的神秘面纱！

内存模型定义是什么
---------

既然要了解 happens-before 原则，我们得先知道 The Go Memory Model（Go 内存模型）定义的是什么，官方解释如下：

> The Go memory model specifies the conditions under which reads of a variable in one goroutine can be guaranteed to observe values produced by writes to the same variable in a different goroutine.

在 Go 内存模型规定：“在一个 goroutine 中读取一个变量时，可以保证观察到不同 goroutine 中对同一变量的写入所产生的值” 的条件。

这是学习后续知识的一个大前提。

happens-before 是什么
------------------

Happens Before 是一个专业术语，与 Go 语言没有直接关系，也就是并非是特有的。用大白话来讲，其定义是：

>  在一个多线程程序中，假设存在 A 和 B 两个操作，如果 A 操作在 B 操作之前发生（A happens-before B），那么 A 操作对内存的影响将会对执行 B 的线程可见。

A 不一定 happens-before B
----------------------

从 happens-before 定义来看，我们可以反过来想。那就是：

>  在同一个（相同）线程中，如果都执行 A 和 B 操作，并且 A 的声明一定在 B 之前，那么 A 一定先于（happens-before）B 发生。

以下述 Go 代码例子：

```
var A int
var B int

func main() {
 A = B + 1  (1)
 B = 1      (2)
}
```

该代码是在同一个 main goroutine，全局变量 A 在变量 B 之前声明。

在 main 函数中，代码行 (1)，也在代码行 (2) 之前。因此我们可以得出 (1) 一定会在 (2) 前执行，对吗？

答案是：错误的，因为 A happens-before B 并不意味着 A 操作一定会在 B 操作之前发生。

实际上在编译器中，上述代码在汇编的真正执行顺序如下：

```
 0x0000 00000 (main.go:7) MOVQ "".B(SB), AX
 0x0007 00007 (main.go:7) INCQ AX
 0x000a 00010 (main.go:7) MOVQ AX, "".A(SB)
 0x0011 00017 (main.go:8) MOVQ $1, "".B(SB)
```

*   (2)：加载 B 到寄存器 AX。
    
*   (2)：进行 B = 1 赋值，在代码中执行为 INCQ 自增。
    
*   (1)：将寄存器 AX 中值加上 1 后赋值给 A。
    

通过上述分析，我们可以得知。在代码行 (1) 在 (2) 之前，但确实 (2) 比 (1) 更早执行。

那么这是不是意味着违反了 happens-before 的设计原则，毕竟这可是同个线程里的操作，Go 编译器有 BUG？

其实不然，因为对 A 的赋值实质上对 B 的赋值没有影响。所以并没有违反 happens-before 的设计原则。

Go 语言中的 happens-before
----------------------

在 《The Go Memory Model》 中，给出了 Go 语言中 Happens Before 的明确语言定义。

以下术语将会在介绍中用到：

*   变量 v：一个指代性的变量，用于示例演示。
    
*   读 r：代表读操作。
    
*   写 w：代表写操作。
    

### 定义

在满足如下两点条件下，允许对变量 v 的读 r 观察对 v 的写 w：

1.  r 在 w 之前没有发生。
    
2.  没有其他写到 v 的 w' 发生在 w 之后但在 r 之前。
    

为了保证变量 v 的读 r 观察到对 v 的特定写 w，确保 w 是唯一允许 r 观察的写。

因此如果以下两点都成立，就能保证 r 能观察到 w ：

1.  w 发生在 r 之前。
    
2.  对共享变量 v 的任何其他写入都发生在 w 之前或 r 之后。
    

这看起来比较生涩，接下来我们以《The Go Memory Model》 中具体的 channel 例子来进行进一步说明，会更好理解一些。

Go Channel 实例
-------------

在 Go 语言中提倡不要通过共享内存来进行通讯；相反，应当通过通讯来共享内存：

> Do not communicate by sharing memory; instead, share memory by communicating.

因此在 Go 工程中，Channel 是一个非常常用的语法。在原则上其需要遵守：

1.  一个 channel 上的发送是在该 channel 的相应接收完成之前发生的。
    
2.  channel 的关闭发生在接收之前，因为通道被关闭而返回一个零值。
    
3.  一个无缓冲 channel 的接收发生在该 channel 的发送完成之前。
    
4.  一个容量为 C 的 channel 上，第 k 次接收发生在该 channel 的第 k+C 次发送完成之前。
    

接下来根据这四条原则，我们逐一给出例子，用于学习和理解。

例子 1
----

Go channel 例子 1，你认为输出的结果是什么。如下：

```
var c = make(chan int, 10)
var a string

func f() {
 a = "炸煎鱼"   (1)
 c <- 0        (2)
}

func main() {
 go f()
 <-c           (3)
 print(a)      (4)
}

```

答案是空字符串吗？

程序最终结果是正常输出 “炸煎鱼” 的，原因如下：

*   (1) happens-before (2) 。
    
*   (4) happens-after (3)。
    

当然，最后 (1) 写入变量 a 的操作，必然 happens-before 于 (4) print 方法，因此正确的输出了 “炸煎鱼”。

能够满足 “一个 channel 上的发送是在该 channel 的相应接收完成之前发生的”。

例子 2
----

主要是确保了关闭管道时的行为。只需要在前面的例子中，替换 `c <- 0` 成 `close(c)` 就能够产生具有相同的行为保证的程序。

能够满足 “channel 的关闭发生在接收之前，因为通道被关闭而返回一个零值”。

例子 3
----

Go channel 例子 3，你认为输出的结果是什么。如下：

```
var c = make(chan int)
var a string

func f() {
 a = "煎鱼进脑子了"    (1)
 <-c                 (2)
}

func main() {
 go f()
 c <- 0              (3)
 print(a)            (4)
}

```

答案是空字符串吗？

程序最终结果是正常输出 “煎鱼进脑子了” 的，原因如下：

*   (2) happens-before (3)。
    
*   (1) happens-before (4)。
    

能够满足 “一个无缓冲 channel 的接收发生在该 channel 的发送完成之前”。

如果我们把无缓冲改为 `make(chan int, 1)`，也就是带缓冲的 channel，则无法保证正常的输出 “煎鱼进脑子了”。

例子 4
----

Go channel 例子 4，这个程序为工作列表中的每个条目启动一个 goroutine，但 goroutine 使用 channel 进行协调，以确保每次最多只有三个工作函数在运行。

代码如下：

```
var limit = make(chan int, 3)

func main() {
 for _, w := range work {
  go func(w func()) {
   limit <- 1
   w()
   <-limit
  }(w)
 }
 select{}
}
```

能够满足 “一个容量为 C 的 channel 上，第 k 次接收发生在该 channel 的第 k+C 次发送完成之前”。

总结
--

在本文中，我们针对 happens-before 原则进行了基本的说明。同时结合 Go 语言中实际的 happens-before 和 happens-after 的场景进了展示和讲解。

实际上，在日常的开发工作中，happens-before 原则基本已经深入到潜意识中，就跟设计模式一样。会不知觉就应用到，但是若我们希望更进一步的对 Go 语言等内存模型就行研究和理解，就必须对这个基本理念有所认知。

你平时有没有注意到这块的问题呢，欢迎大家留言和讨论！

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，学习 Go 语言可以看 [Go 学习地图和路线](https://github.com/eddycjy/go-developer-roadmap)，欢迎 Star 催更。

参考
--

*   The Go Memory Model
    
*   Go内存模型&Happen-Before（一）
    
*   GoLang 内存模型
    
*   Golang happens before & channel
    
*   Go 内存模型


================================================
FILE: content/posts/go/news-slices-maps.md
================================================
---
title: "Go 提案：增加泛型版 slices 和 maps 新包"
date: 2021-12-31T12:54:57+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

现在是 2021 年 8 月份了，根据 Go 语言发布周期的 2，8 原则。Go 1.17 即将发布，在写这篇文章时，现在已经进行到了 rc2：

![](https://files.mdnice.com/user/3610/ced4caa3-98ac-4c8a-8077-c72e11f69b56.png)

这意味着离 Go1.18 释出泛型的正式支持又近了一点点，社区中讨论泛型相关的周边功能的声音又多了起来。

今天要讨论的泛型版功能支持也是如此，分别包含：map（#47330）、slice（#45955）、container/set（#47331） 三种通用类型的支持。

我们主要展开 maps 和 slices，其余的都大同小异，理解核心思想就好。

## maps

该提案建议定义一个新的包 maps，它将提供可用于任何类型的 map 的函数：

![](https://files.mdnice.com/user/3610/fc067e0f-0972-4f92-898e-d64404b5bfa4.png)

下面的描述侧重于描述 API 的提供：

```golang
package maps

func Keys[K comparable, V any](m map[K]V) []K

func Values[K comparable, V any](m map[K]V) []V

func Equal[K, V comparable](m1, m2 map[K]V) bool

func EqualFunc[K comparable, V1, V2 any](m1 map[K]V1, m2 map[K]V2, cmp func(V1, V2) bool) bool

func Clear[K comparable, V any](m map[K]V)

func Clone[K comparable, V any](m map[K]V) map[K]V

func Add[K comparable, V any](dst, src map[K]V)

func Filter[K comparable, V any](m map[K]V, keep func(K, V) bool)
```
- Keys：返回 map 的键值。这些键将是一个不确定的顺序。
- Values：返回 map 值。这些值将以不确定的顺序出现。
- Equal：匹配两个 map 是否包含相同的键/值对。
- EqualFunc：EqualFunc 与 Equal 类似，但使用 cmp 进行数值比较。
- Clear：从 map 中清除所有条目，使其为空。
- Clone：返回一个 map 的副本，这是一个浅层克隆。新的键和值使用普通的赋值来设置。
- Add：将 src 中的所有键/值对添加到 dst 中。当 src 中的一个键已经存在于 dst 中时，dst 中的值将被 src 中的键相关的值覆盖。
- Filter：过滤器从 map 中删除任何 keep 返回结果为 false 的键/值对。

## slice

该提案建议定义一个新的包 slices，它将提供可用于任何类型的 slice 的函数：

![](https://files.mdnice.com/user/3610/8086fdea-63ee-4c73-aa4b-95b3c647d8e6.png)

下面的描述侧重于描述 API 的提供：

```golang
package slices

import "constraint"

func Equal[T comparable](s1, s2 []T) bool

func EqualFunc[T1, T2 any](s1 []T1, s2 []T2, eq func(T1, T2) bool) bool

func Compare[T constraints.Ordered](s1, s2 []T) int

func CompareFunc[T any](s1, s2 []T, cmp func(T, T) int) int

func Index[T comparable](s []T, v T) int

func IndexFunc[T any](s []T, f func(T) bool) int

func Contains[T comparable](s []T, v T) bool

func Insert[S constraints.Slice[T], T any](s S, i int, v ...T) S

func Delete[S constraints.Slice[T], T any](s S, i, j int) S

func Clone[S constraints.Slice[T], T any](s S) S
```
- Equal：检查两个切片是否相等，以长度和元素值来比较。
- EqualFunc：检查两个切片是否相等，以所传入的匹配函数来比较。
- Compare/CompareFunc：
    - Compare 比较两个切片 s1 和 s2 的元素。
    - CompareFunc 与 Compare 类似，在每一对元素上使用所传入的比较函数。
- Index：
    - Index 返回值 v 在切片 s 中第一次出现的索引，如果不存在，则返回-1。
    - IndexFunc 返回满足f(c)的第一个元素在s中的索引，如果没有则返回-1。
- Contains：检查值 v 是否存在于切片 s 中。

插入、删除、克隆的 API 比较常见，这里我就不展开了。在通用类型的切片有一些比较特殊的 API：

```golang
func Compact[S constraints.Slice[T], T comparable](s S) S

func CompactFunc[S constraints.Slice[T], T any](s S, cmp func(T, T) bool) S

func Grow[S constraints.Slice[T], T any](s S, n int) S

func Clip[S constraints.Slice[T], T any](s S) S
```
- Compact/CompactFunc：
    - Compact 将连续运行的相等元素替换为单一的副本。这就像 Unix 中的 uniq 命令。会直接修改切片 s 的内容，不会重新创建一个。
    - CompactFunc 与 Compact 方法类似，但是使用一个比较函数来匹配。
- Grow：如果有必要，Grow 会增长切片的容量，以保证另外 n 个元素的空间。在 Grow(n) 之后，至少有 n 个元素可以被添加到分片中而不需要再分配。如果 n 是负数或者太大，无法分配内存，Grow 将陷入恐慌。
- Clip：从切片中移除未使用的容量，返回s[:len(s):len(s)]。

## 总结

如果这些提议被接受，这几个新包将被包含在实现泛型后的第一个Go版本中（我们目前预计将是Go 1.18）。

从 issues 的讨论来看，通用类型的新包支持很大概率会实现，主要争议在实现细节，例如：性能、命名、规范等。

实现后值得期待，又是一次生产力的优化！

================================================
FILE: content/posts/go/news115.md
================================================
---
title: "分享 Go 最近的几件周边大小事"
date: 2021-12-31T12:55:17+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

最近可能是因为 Q4 了，又恰逢 Go1.18 快要发布，各路 Go 语言的新消息层出不穷。

今天煎鱼带大家一起来了解下最近社区发生的几件大小事，当然，我只讲一些核心的内容。

![](https://files.mdnice.com/user/3610/d6f8bfde-141c-405b-8ec5-779d31b0283d.png)

## Go 诞生 12 年

在 2021 年 11 月 10 日，是 Go 语言开源版本的 12 岁生日。Go 官方博客发表《[Twelve Years of Go](https://go.dev/blog/12years "Twelve Years of Go")》。

主体内容分为三块介绍：
- 回顾过去一年的核心变更。
- 展望明年的特性计划。
- 介绍今年做的 Go 相关分享。

### 回顾过去

是对过去一年的版本更新进行说明：
- Go1.16：默认启用 Go modules，增加 MacOS ARM64 的支持，新支持文件系统接口和嵌入文件的特性。
- Go1.17：Go 函数改为基于寄存器的调用规范（提高了 5~15% 的性能），增加 Windows ARM64 支持，还引入了模块裁剪等功能。
- Go1.18：预计支持模糊测试（Go fuzzing）、泛型等强大的新特性。

核心总结：今年大力推动 Go modules，提高了 Go 函数的性能，增加了更多的计算机架构支持，以及若干改进和优化（例如：TLS）。

也为了推广 Go 语言，做出了更多的努力和资料培训（Gin 也因此更上了一层楼）。

### 后续安排

我们核心关注泛型方面的消息，泛型将会是 2022 年的核心重点之一。规划如下：
- Go 1.18 中的初始版本只是泛型的开始，将会在此版本使用泛型并学习哪些有效、哪些无效。
- 在确定泛型的 “实践” 后，会输出 “最佳实践”，并决定何时追加泛型实现到标准库和第三方库中。
- 期待在 **Go1.19**（也就是 2022.08）及更高版本将**进一步完善泛型**的设计和实现，并将它们进一步整合到整体的 Go 体验中（也就是工具链等）。

核心总结：明年要继续大力推进泛型，先尝鲜，再出最佳实践，进而融合进 Go 体系中，路还比较远。

## 分享知识

今年 Go 团队为了推广 Go 语言的配套知识体系，还发布了一堆教程：
- 《[guide to databases in Go](https://golang.org/doc/database/ "guide to databases in Go")》：Go 数据库指南。
- 《[guide to developing modules](https://golang.org/doc/#developing-modules "guide to developing modules")》：Go 开发模块指南。
- 《[用 Go 和 Gin 开发 RESTful API](https://golang.org/doc/tutorial/web-service-gin "用 Go 和 Gin 开发 RESTful API")》：用 Go 和 Gin 开发 RESTful API，有种把 Gin 作为推荐框架的感觉了。

这两天 Go 团队在 Google Open Source Live 举办了第二次年度 Go 日：

![来源于 youtube，还自带字幕翻译](https://files.mdnice.com/user/3610/ba469b39-4395-4f3c-9e82-37e4a1b8812e.png)  

分享了如下话题：
- 《[Using Generics in Go](https://www.youtube.com/watch?v=nr8EpUO9jhw "Using Generics in Go")》：介绍了泛型以及如何有效地使用它们。
- 《[Modern Enterprise Applications](https://www.youtube.com/watch?v=5fgG1qZaV4w "Modern Enterprise Applications")》：展示了 Go 在企业现代化中所扮演的角色。
- 《[Building Better Projects with the Go Editor](https://www.youtube.com/watch?v=jMyzsp2E_0U "Building Better Projects with the Go Editor")》：展示了VS Code Go的集成工具如何帮助你浏览代码、调试测试等。
- 《[From Proof of Concept to Production](https://www.youtube.com/watch?v=e7PtBOsTpXE "From Proof of Concept to Production")》：介绍美国运通公司如何在其支付和奖励平台中使用 Go。

有个别 Go 话题还是很不错的，尤其是泛型的快速了解。这在该视频网站上还有比较顺畅的字幕翻译，阅读基本没问题。

可自行选择食用。

## 泛型新语法和 Playground

### GoTip Playground

在之前我们是通过 `go2goplay.golang.org` 来进行一些在线泛型的例子玩耍。

在经历了一定时间的迭代后，泛型的新特性多了不少，由新版的 Playground（gotipplay.golang.org）来替换使用：

![https://gotipplay.golang.org](https://files.mdnice.com/user/3610/53d4f09e-689b-445f-862c-f18b91a359f8.png)

主要特点：所运行的代码**基于 tip 版本**，再也不用自己拉代码了。在 select 控件上也多了不少例子的展示。

后续大概率会增加泛型的实践。

### 约束语法

需要注意的一点，最新的 Go 泛型约束语法又又又变了。从原本的 “,” 改为了 "|"。

![Type Parameters Proposal](https://files.mdnice.com/user/3610/5f1f20c6-0d81-43a1-a1c3-334213546fc7.png)

原本如下：

```golang
type T interface {
 type int, int8, int16, int32, int64, uint, uint8, uint16, uint32, uint64, uintptr, float32, float64, complex64, complex128, string
}
```

新的如下：

```golang
type T interface {
	~int | ~int8 | ~int16 | ~int32 | ~int64 |
		~uint | ~uint8 | ~uint16 | ~uint32 | ~uint64 | ~uintptr |
		~float32 | ~float64 |
		~string
}
```

## 新搜索体验

近期官方对文档站 `pkg.go.dev` 做了一轮搜索优化。主要分为如下：
- 按包搜索。
- 按符号搜索。

若是按包搜索，将会对相关包的搜索结果进行分组，优化后不再是流水式展示，而是聚类，根据归类后分组展示。

如下图：

![按包搜索](https://files.mdnice.com/user/3610/5e12b6ee-995a-4dd4-af4d-8aec6f57f580.png)

若是按符号搜索，将可以对包内的 “符号” 实现更精准的搜索，例如：常量、变量、函数、类型、字段或方法。

如下图：

![按符号搜索](https://files.mdnice.com/user/3610/52697a9c-00f1-46d8-9068-976d85dcb6d0.png)

搜索效率是提高了不少的。以后会不会向完整的代码搜索和关联的方向发展，也是个值得思考的问题。

## 总结

今天给大家介绍了 Go 语言社区最近发生的好几件大小事，每一个展开都是一篇新的文章。
例如：可以了解为什么泛型要从 “,” 改为 “|” 的格式，肯定是有原因的。

这些内容（以及 Go1.18 的新特性），我会在后续的文章继续深入展开和介绍。

欢迎大家关注我，获取一手的 Go 社区快讯和知识：）

================================================
FILE: content/posts/go/nil-func.md
================================================
---
title: "Go 读者提问：值为 nil 也能调用函数，太神奇了吧？"
date: 2021-12-31T12:55:27+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

最近在我们 Go 的技术交流群里，有一个小伙伴提了一个程序方面的问题，还挺有意思的，分享给大家。

![](https://files.mdnice.com/user/3610/0774f643-81a2-4458-b557-05c81a9572ef.png)

## 示例

示例程序如下：

```golang
type T struct{}

func (t *T) Hello() string {
	if t == nil {
		fmt.Println("脑子进煎鱼了")
		return ""
	}

	return "煎鱼进脑子了"
}

func main() {
	var t *T
	t.Hello()
```

这段程序的运行结果是什么？

从程序的分析来看，变量 `t` 并没有初始化，只是声明了类型。然后就直接调用了 `Hello` 方法，像是 nil 调用函数，理论上应该出现恐慌（panic）。

运行结果是：

```
panic: runtime error: invalid memory address or nil pointer dereference
```

对不对呢？

显然，真正的运行结果是：

```
脑子进煎鱼了
```

请你思考一下，想想这是为什么？

## 为什么

问题的原因是：很多小伙伴认为变量 `t` 的值都是 nil 了，不应该还能调用到才对。

更抽象化来讲，就是 ”程序是如何检查对象指针来寻找和调度所需函数“。

实际上，在 Go 中，表达式 `Expression.Name` 的语法，所调用的函数完全由 `Expression` 的类型决定。

其调用函数的指向不是由该表达式的特定运行时值来决定，包括我们前面所提到的 nil。

具体如下：

```golang
func (p *Sometype) Somemethod (firstArg int) {}
```

本质上是：

```golang
func SometypeSomemethod(p *Sometype, firstArg int) {}
```

这么一看，其实大家应该都明白了。

上述入参 `p *Sometype` 是有具体上下文类型的，自然而然也就能调用到相应的方法。如果是没有任何上下文类型的，例如：`nil.Somemethod` 方法来调用，那肯定就是无法运行的。

与值是不是 nil，是什么，没有太多直接的影响。只要有预期类型的上下文就可以了。

## 总结

今天给大家分享了一个 Go 语言里面的一个小细节，平时可能很多人没注意到，毕竟 IDE 也会标黄，会避开这个问题点。

在理解 Go 的设计和思考上，我们是需要清晰其背后的原因和逻辑的，也就是类型决定其调用，而不是值（容易误判）。

你有没有遇到过其它的细节问题呢，欢迎交流：）

================================================
FILE: content/posts/go/panic/2019-05-21-panic-and-recover.md
================================================
---

title:      "深入理解 Go panic and recover"
date:       2019-05-21 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

作为一个 gophper，我相信你对于 `panic` 和 `recover` 肯定不陌生，但是你有没有想过。当我们执行了这两条语句之后。底层到底发生了什么事呢？前几天和同事刚好聊到相关的话题，发现其实大家对这块理解还是比较模糊的。希望这篇文章能够从更深入的角度告诉你为什么，它到底做了什么事？

## 思考

### 一、为什么会中止运行

```
func main() {
	panic("EDDYCJY.")
}
```

输出结果：

```
$ go run main.go
panic: EDDYCJY.

goroutine 1 [running]:
main.main()
	/Users/eddycjy/go/src/github.com/EDDYCJY/awesomeProject/main.go:4 +0x39
exit status 2
```

请思考一下，为什么执行 `panic` 后会导致应用程序运行中止？（而不是单单说执行了 `panic` 所以就结束了这么含糊）

### 二、为什么不会中止运行

```
func main() {
	defer func() {
		if err := recover(); err != nil {
			log.Printf("recover: %v", err)
		}
	}()

	panic("EDDYCJY.")
}
```

输出结果：

```
$ go run main.go 
2019/05/11 23:39:47 recover: EDDYCJY.
```

请思考一下，为什么加上 `defer` + `recover` 组合就可以保护应用程序？

### 三、不设置 defer 行不

上面问题二是 `defer` + `recover` 组合，那我去掉 `defer` 是不是也可以呢？如下：

```
func main() {
	if err := recover(); err != nil {
		log.Printf("recover: %v", err)
	}

	panic("EDDYCJY.")
}
```

输出结果：

```
$ go run main.go
panic: EDDYCJY.

goroutine 1 [running]:
main.main()
	/Users/eddycjy/go/src/github.com/EDDYCJY/awesomeProject/main.go:10 +0xa1
exit status 2
```

竟然不行，啊呀毕竟入门教程都写的 `defer` + `recover` 组合 “万能” 捕获。但是为什么呢。去掉 `defer` 后为什么就无法捕获了？

请思考一下，为什么需要设置 `defer` 后 `recover` 才能起作用？

同时你还需要仔细想想，我们设置 `defer` + `recover` 组合后就能无忧无虑了吗，各种 “乱” 写了吗？

### 四、为什么起个 goroutine 就不行

```
func main() {
	go func() {
		defer func() {
			if err := recover(); err != nil {
				log.Printf("recover: %v", err)
			}
		}()
	}()

	panic("EDDYCJY.")
}
```

输出结果：

```
$ go run main.go 
panic: EDDYCJY.

goroutine 1 [running]:
main.main()
	/Users/eddycjy/go/src/github.com/EDDYCJY/awesomeProject/main.go:14 +0x51
exit status 2
```

请思考一下，为什么新起了一个 `Goroutine` 就无法捕获到异常了？到底发生了什么事...

## 源码

接下来我们将带着上述 4+1 个小思考题，开始对源码的剖析和分析，尝试从阅读源码中找到思考题的答案和更多为什么

### 数据结构

```
type _panic struct {
	argp      unsafe.Pointer
	arg       interface{} 
	link      *_panic 
	recovered bool
	aborted   bool 
}
```

在 `panic` 中是使用 `_panic` 作为其基础单元的，每执行一次 `panic` 语句，都会创建一个 `_panic`。它包含了一些基础的字段用于存储当前的 `panic` 调用情况，涉及的字段如下：

- argp：指向 `defer` 延迟调用的参数的指针
- arg：`panic` 的原因，也就是调用 `panic` 时传入的参数
- link：指向上一个调用的 `_panic`
- recovered：`panic` 是否已经被处理，也就是是否被 `recover`
- aborted：`panic` 是否被中止

另外通过查看 `link` 字段，可得知其是一个链表的数据结构，如下图：

![image](http://wx3.sinaimg.cn/large/006fVPCvly1g2muc73jp1j30hc099q2x.jpg)

### 恐慌 panic

```
func main() {
	panic("EDDYCJY.")
}
```

输出结果：

```
$ go run main.go
panic: EDDYCJY.

goroutine 1 [running]:
main.main()
	/Users/eddycjy/go/src/github.com/EDDYCJY/awesomeProject/main.go:4 +0x39
exit status 2
```

我们去反查一下 `panic` 处理具体逻辑的地方在哪，如下：

```
$ go tool compile -S main.go
"".main STEXT size=66 args=0x0 locals=0x18
	0x0000 00000 (main.go:23)	TEXT	"".main(SB), ABIInternal, $24-0
	0x0000 00000 (main.go:23)	MOVQ	(TLS), CX
	0x0009 00009 (main.go:23)	CMPQ	SP, 16(CX)
	...
	0x002f 00047 (main.go:24)	PCDATA	$2, $0
	0x002f 00047 (main.go:24)	MOVQ	AX, 8(SP)
	0x0034 00052 (main.go:24)	CALL	runtime.gopanic(SB)
```

显然汇编代码直指内部实现是 `runtime.gopanic`，我们一起来看看这个方法做了什么事，如下（省略了部分）：

```
func gopanic(e interface{}) {
	gp := getg()
	...
	var p _panic
	p.arg = e
	p.link = gp._panic
	gp._panic = (*_panic)(noescape(unsafe.Pointer(&p)))
    
	for {
		d := gp._defer
		if d == nil {
			break
		}

		// defer...
		...
		d._panic = (*_panic)(noescape(unsafe.Pointer(&p)))

		p.argp = unsafe.Pointer(getargp(0))
		reflectcall(nil, unsafe.Pointer(d.fn), deferArgs(d), uint32(d.siz), uint32(d.siz))
		p.argp = nil

		// recover...
		if p.recovered {
			...
			mcall(recovery)
			throw("recovery failed") // mcall should not return
		}
	}

	preprintpanics(gp._panic)

	fatalpanic(gp._panic) // should not return
	*(*int)(nil) = 0      // not reached
}
```

- 获取指向当前 `Goroutine` 的指针
- 初始化一个 `panic` 的基本单位 `_panic` 用作后续的操作
- 获取当前 `Goroutine` 上挂载的 `_defer`（数据结构也是链表）
- 若当前存在 `defer` 调用，则调用 `reflectcall` 方法去执行先前 `defer` 中延迟执行的代码，若在执行过程中需要运行 `recover` 将会调用 `gorecover` 方法
- 结束前，使用 `preprintpanics` 方法打印出所涉及的 `panic` 消息
- 最后调用 `fatalpanic` 中止应用程序，实际是执行 `exit(2)` 进行最终退出行为的

通过对上述代码的执行分析，可得知 `panic` 方法实际上就是处理当前 `Goroutine(g)` 上所挂载的 `._panic` 链表（所以无法对其他 `Goroutine` 的异常事件响应），然后对其所属的 `defer` 链表和 `recover` 进行检测并处理，最后调用退出命令中止应用程序

### 无法恢复的恐慌 fatalpanic

```
func fatalpanic(msgs *_panic) {
	pc := getcallerpc()
	sp := getcallersp()
	gp := getg()
	var docrash bool

	systemstack(func() {
		if startpanic_m() && msgs != nil {
		    ...
			printpanics(msgs)
		}

		docrash = dopanic_m(gp, pc, sp)
	})

	systemstack(func() {
		exit(2)
	})

	*(*int)(nil) = 0
}
```

我们看到在异常处理的最后会执行该方法，似乎它承担了所有收尾工作。实际呢，它是在最后对程序执行 `exit` 指令来达到中止运行的作用，但在结束前它会通过 `printpanics` 递归输出所有的异常消息及参数。代码如下：

```
func printpanics(p *_panic) {
	if p.link != nil {
		printpanics(p.link)
		print("\t")
	}
	print("panic: ")
	printany(p.arg)
	if p.recovered {
		print(" [recovered]")
	}
	print("\n")
}
```

所以不要以为所有的异常都能够被 `recover` 到，实际上像 `fatal error` 和 `runtime.throw` 都是无法被 `recover` 到的，甚至是 oom 也是直接中止程序的，也有反手就给你来个 `exit(2)` 教做人。因此在写代码时你应该要相对注意些，“恐慌” 是存在无法恢复的场景的

### 恢复 recover

```
func main() {
	defer func() {
		if err := recover(); err != nil {
			log.Printf("recover: %v", err)
		}
	}()

	panic("EDDYCJY.")
}
```

输出结果：

```
$ go run main.go 
2019/05/11 23:39:47 recover: EDDYCJY.
```

和预期一致，成功捕获到了异常。但是 `recover` 是怎么恢复 `panic` 的呢？再看看汇编代码，如下：

```
$ go tool compile -S main.go
"".main STEXT size=110 args=0x0 locals=0x18
	0x0000 00000 (main.go:5)	TEXT	"".main(SB), ABIInternal, $24-0
	...
	0x0024 00036 (main.go:6)	LEAQ	"".main.func1·f(SB), AX
	0x002b 00043 (main.go:6)	PCDATA	$2, $0
	0x002b 00043 (main.go:6)	MOVQ	AX, 8(SP)
	0x0030 00048 (main.go:6)	CALL	runtime.deferproc(SB)
	...
	0x0050 00080 (main.go:12)	CALL	runtime.gopanic(SB)
	0x0055 00085 (main.go:12)	UNDEF
	0x0057 00087 (main.go:6)	XCHGL	AX, AX
	0x0058 00088 (main.go:6)	CALL	runtime.deferreturn(SB)
	...
	0x0022 00034 (main.go:7)	MOVQ	AX, (SP)
	0x0026 00038 (main.go:7)	CALL	runtime.gorecover(SB)
	0x002b 00043 (main.go:7)	PCDATA	$2, $1
	0x002b 00043 (main.go:7)	MOVQ	16(SP), AX
	0x0030 00048 (main.go:7)	MOVQ	8(SP), CX
	...
	0x0056 00086 (main.go:8)	LEAQ	go.string."recover: %v"(SB), AX
	...
	0x0086 00134 (main.go:8)	CALL	log.Printf(SB)
	...
```

通过分析底层调用，可得知主要是如下几个方法：
- runtime.deferproc
- runtime.gopanic
- runtime.deferreturn
- runtime.gorecover

在上小节中，我们讲述了简单的流程，`gopanic` 方法会调用当前 `Goroutine` 下的 `defer` 链表，若 `reflectcall` 执行中遇到 `recover` 就会调用 `gorecover` 进行处理，该方法代码如下：


```
func gorecover(argp uintptr) interface{} {
	gp := getg()
	p := gp._panic
	if p != nil && !p.recovered && argp == uintptr(p.argp) {
		p.recovered = true
		return p.arg
	}
	return nil
}
```

这代码，看上去挺简单的，核心就是修改 `recovered` 字段。该字段是用于标识当前 `panic` 是否已经被 `recover` 处理。但是这和我们想象的并不一样啊，程序是怎么从 `panic` 流转回去的呢？是不是在核心方法里处理了呢？我们再看看 `gopanic` 的代码，如下：


```
func gopanic(e interface{}) {
	...
	for {
		// defer...
		...
		pc := d.pc
		sp := unsafe.Pointer(d.sp) // must be pointer so it gets adjusted during stack copy
		freedefer(d)
		
		// recover...
		if p.recovered {
			atomic.Xadd(&runningPanicDefers, -1)

			gp._panic = p.link
			for gp._panic != nil && gp._panic.aborted {
				gp._panic = gp._panic.link
			}
			if gp._panic == nil { 
				gp.sig = 0
			}

			gp.sigcode0 = uintptr(sp)
			gp.sigcode1 = pc
			mcall(recovery)
			throw("recovery failed") 
		}
	}
    ...
}
```

我们回到 `gopanic` 方法中再仔细看看，发现实际上是包含对 `recover` 流转的处理代码的。恢复流程如下：

- 判断当前 `_panic` 中的 `recover` 是否已标注为处理
- 从 `_panic` 链表中删除已标注中止的 `panic` 事件，也就是删除已经被恢复的 `panic` 事件
- 将相关需要恢复的栈帧信息传递给 `recovery` 方法的 `gp` 参数（每个栈帧对应着一个未运行完的函数。栈帧中保存了该函数的返回地址和局部变量）
- 执行 `recovery` 进行恢复动作

从流程来看，最核心的是 `recovery` 方法。它承担了异常流转控制的职责。代码如下：

```
func recovery(gp *g) {
	sp := gp.sigcode0
	pc := gp.sigcode1

	if sp != 0 && (sp < gp.stack.lo || gp.stack.hi < sp) {
		print("recover: ", hex(sp), " not in [", hex(gp.stack.lo), ", ", hex(gp.stack.hi), "]\n")
		throw("bad recovery")
	}

	gp.sched.sp = sp
	gp.sched.pc = pc
	gp.sched.lr = 0
	gp.sched.ret = 1
	gogo(&gp.sched)
}
```

粗略一看，似乎就是很简单的设置了一些值？但实际上设置的是编译器中伪寄存器的值，常常被用于维护上下文等。在这里我们需要结合 `gopanic` 方法一同观察 `recovery` 方法。它所使用的栈指针 `sp` 和程序计数器 `pc` 是由当前 `defer` 在调用流程中的 `deferproc` 传递下来的，因此实际上最后是通过 `gogo` 方法跳回了 `deferproc` 方法。另外我们注意到：

```
gp.sched.ret = 1
```

在底层中程序将 `gp.sched.ret` 设置为了 1，也就是**没有实际调用** `deferproc` 方法，直接修改了其返回值。意味着默认它已经处理完成。直接转移到 `deferproc` 方法的下一条指令去。至此为止，异常状态的流转控制就已经结束了。接下来就是继续走 `defer` 的流程了


为了验证这个想法，我们可以看一下核心的跳转方法 `gogo` ，代码如下：

```
// void gogo(Gobuf*)
// restore state from Gobuf; longjmp
TEXT runtime·gogo(SB),NOSPLIT,$8-4
	MOVW	buf+0(FP), R1
	MOVW	gobuf_g(R1), R0
	BL	setg<>(SB)

	MOVW	gobuf_sp(R1), R13	// restore SP==R13
	MOVW	gobuf_lr(R1), LR
	MOVW	gobuf_ret(R1), R0
	MOVW	gobuf_ctxt(R1), R7
	MOVW	$0, R11
	MOVW	R11, gobuf_sp(R1)	// clear to help garbage collector
	MOVW	R11, gobuf_ret(R1)
	MOVW	R11, gobuf_lr(R1)
	MOVW	R11, gobuf_ctxt(R1)
	MOVW	gobuf_pc(R1), R11
	CMP	R11, R11 // set condition codes for == test, needed by stack split
	B	(R11)
```

通过查看代码可得知其主要作用是从 `Gobuf` 恢复状态。简单来讲就是将寄存器的值修改为对应 `Goroutine(g)` 的值，而在文中讲了很多次的 `Gobuf`，如下：

```
type gobuf struct {
	sp   uintptr
	pc   uintptr
	g    guintptr
	ctxt unsafe.Pointer
	ret  sys.Uintreg
	lr   uintptr
	bp   uintptr
}
```

讲道理，其实它存储的就是 `Goroutine` 切换上下文时所需要的一些东西

## 拓展

```
const(
	OPANIC       // panic(Left)
	ORECOVER     // recover()
	...
)
...
func walkexpr(n *Node, init *Nodes) *Node {
    ...
	switch n.Op {
	default:
		Dump("walk", n)
		Fatalf("walkexpr: switch 1 unknown op %+S", n)

	case ONONAME, OINDREGSP, OEMPTY, OGETG:
	case OTYPE, ONAME, OLITERAL:
	    ...
	case OPANIC:
		n = mkcall("gopanic", nil, init, n.Left)

	case ORECOVER:
		n = mkcall("gorecover", n.Type, init, nod(OADDR, nodfp, nil))
	...
}
```

实际上在调用 `panic` 和 `recover` 关键字时，是在编译阶段先转换为相应的 OPCODE 后，再由编译器转换为对应的运行时方法。并不是你所想像那样一步到位，有兴趣的小伙伴可以研究一下

## 总结

本文主要针对 `panic` 和 `recover` 关键字进行了深入源码的剖析，而开头的 4+1 个思考题，就是希望您能够带着疑问去学习，达到事半功倍的功效

另外本文和 `defer` 有一定的关联性，因此需要有一定的基础知识。若刚刚看的时候这部分不理解，学习后可以再读一遍加深印象

在最后，现在的你可以回答这几个思考题了吗？说出来了才是真的懂 ：）


================================================
FILE: content/posts/go/pkg/2018-09-28-log.md
================================================
---

title:      "log 标准库"
date:       2018-09-28 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

## 日志

### 输出

```
2018/09/28 20:03:08 EDDYCJY Blog...
```

### 构成

[日期]<空格>[时分秒]<空格>[内容]<\n>

## 源码剖析

### Logger

```
type Logger struct {
	mu     sync.Mutex 
	prefix string
	flag   int
	out    io.Writer
	buf    []byte
}
```

1. mu：互斥锁，用于确保原子的写入
2. prefix：每行需写入的日志前缀内容
3. flag：设置日志辅助信息（时间、文件名、行号）的写入。可选如下标识位：

```
const (
	Ldate         = 1 << iota       // value: 1
	Ltime                           // value: 2
	Lmicroseconds                   // value: 4
	Llongfile                       // value: 8
	Lshortfile                      // value: 16
	LUTC                            // value: 32
	LstdFlags     = Ldate | Ltime   // value: 3
)
```

- Ldate：当地时区的格式化日期：2009/01/23
- Ltime：当地时区的格式化时间：01:23:23
- Lmicroseconds：在 Ltime 的基础上，增加微秒的时间数值显示
- Llongfile：完整的文件名和行号：/a/b/c/d.go:23
- Lshortfile：当前文件名和行号：d.go：23，会覆盖 Llongfile 标识
- LUTC：如果设置 Ldate 或 Ltime，且设置 LUTC，则优先使用 UTC 时区而不是本地时区
- LstdFlags：Logger 的默认初始值（Ldate 和 Ltime）

4. out：io.Writer
5. buf：用于存储将要写入的日志内容

### New

```
func New(out io.Writer, prefix string, flag int) *Logger {
	return &Logger{out: out, prefix: prefix, flag: flag}
}

var std = New(os.Stderr, "", LstdFlags)
```

New 方法用于初始化 Logger，接受三个初始参数，可以定制化而在 log 包内默认会初始一个 std，它指向标准输入流。而默认的标准输出、标准错误就是显示器（输出到屏幕上），标准输入就是键盘。辅助的时间信息默认为 `Ldate | Ltime`，也就是 `2009/01/23 01:23:23`

```
// os
var (
	Stdin  = NewFile(uintptr(syscall.Stdin), "/dev/stdin")
	Stdout = NewFile(uintptr(syscall.Stdout), "/dev/stdout")
	Stderr = NewFile(uintptr(syscall.Stderr), "/dev/stderr")
)
```

- Stdin：标准输入
- Stdout：标准输出
- Stderr：标准错误

### Getter

- Flags
- Prefix

### Setter

- SetFlags
- SetPrefix
- SetOutput

### Print*, Fatal*, Panic*

```
func Print(v ...interface{}) {
	std.Output(2, fmt.Sprint(v...))
}

func Printf(format string, v ...interface{}) {
	std.Output(2, fmt.Sprintf(format, v...))
}

func Println(v ...interface{}) {
	std.Output(2, fmt.Sprintln(v...))
}

func Fatal(v ...interface{}) {
	std.Output(2, fmt.Sprint(v...))
	os.Exit(1)
}

func Panic(v ...interface{}) {
	s := fmt.Sprint(v...)
	std.Output(2, s)
	panic(s)
}

...
```

这一部分介绍最常用的日志写入方法，从源码可得知 `Xrintln`、`Xrintf` 函数 **换行**、**可变参数**都是通过 `fmt` 标准库的方法去实现的

`Fatal` 和 `Panic` 是通过 `os.Exit(1)`、`panic(s)` 集成实现的。而具体的组装逻辑是通过 `Output` 方法实现的

#### Logger.Output

```
func (l *Logger) Output(calldepth int, s string) error {
	now := time.Now() // get this early.
	var file string
	var line int
	l.mu.Lock()
	defer l.mu.Unlock()
	if l.flag&(Lshortfile|Llongfile) != 0 {
		// Release lock while getting caller info - it's expensive.
		l.mu.Unlock()
		var ok bool
		_, file, line, ok = runtime.Caller(calldepth)
		if !ok {
			file = "???"
			line = 0
		}
		l.mu.Lock()
	}
	l.buf = l.buf[:0]
	l.formatHeader(&l.buf, now, file, line)
	l.buf = append(l.buf, s...)
	if len(s) == 0 || s[len(s)-1] != '\n' {
		l.buf = append(l.buf, '\n')
	}
	_, err := l.out.Write(l.buf)
	return err
}
```

Output 方法，简单来讲就是将写入的日志事件信息组装并输出，它会根据 flag 标识位的不同来使用 `runtime.Caller` 去获取当前 goroutine 所执行的函数文件、行号等调用信息（log 标准库中默认深度为 2）。另外如果结尾不是换行符 `\n`，将自动补全一个换行

#### Logger.formatHeader

```
func (l *Logger) formatHeader(buf *[]byte, t time.Time, file string, line int) {
	*buf = append(*buf, l.prefix...)
	if l.flag&(Ldate|Ltime|Lmicroseconds) != 0 {
		if l.flag&LUTC != 0 {
			t = t.UTC()
		}
		if l.flag&Ldate != 0 {
			year, month, day := t.Date()
			itoa(buf, year, 4)
			*buf = append(*buf, '/')
			itoa(buf, int(month), 2)
			*buf = append(*buf, '/')
			itoa(buf, day, 2)
			*buf = append(*buf, ' ')
		}
		if l.flag&(Ltime|Lmicroseconds) != 0 {
			hour, min, sec := t.Clock()
			itoa(buf, hour, 2)
			*buf = append(*buf, ':')
			itoa(buf, min, 2)
			*buf = append(*buf, ':')
			itoa(buf, sec, 2)
			if l.flag&Lmicroseconds != 0 {
				*buf = append(*buf, '.')
				itoa(buf, t.Nanosecond()/1e3, 6)
			}
			*buf = append(*buf, ' ')
		}
	}
	if l.flag&(Lshortfile|Llongfile) != 0 {
		if l.flag&Lshortfile != 0 {
			short := file
			for i := len(file) - 1; i > 0; i-- {
				if file[i] == '/' {
					short = file[i+1:]
					break
				}
			}
			file = short
		}
		*buf = append(*buf, file...)
		*buf = append(*buf, ':')
		itoa(buf, line, -1)
		*buf = append(*buf, ": "...)
	}
}
```

该方法主要是用于格式化日志头（前缀），根据入参不同的标识位，添加分隔符和对应的值到日志信息中。执行流程如下：

（1）如果不是空值，则将 prefix 写入 buf

（2）如果设置 `Ldate`、`Ltime`、`Lmicroseconds`，则对应将日期和时间写入 buf

（3）如果设置 `Lshortfile`、`Llongfile`，则对应将文件和行号信息写入 buf

#### Logger.itoa

```
func itoa(buf *[]byte, i int, wid int) {
	// Assemble decimal in reverse order.
	var b [20]byte
	bp := len(b) - 1
	for i >= 10 || wid > 1 {
		wid--
		q := i / 10
		b[bp] = byte('0' + i - q*10)
		bp--
		i = q
	}
	// i < 10
	b[bp] = byte('0' + i)
	*buf = append(*buf, b[bp:]...)
}
```

该方法主要用于将整数转换为定长的十进制 ASCII，同时给出负数宽度避免左侧补 0。另外会以相反的顺序组合十进制 

### 如何定制化 Logger

在标准库内，可通过其开放的 New 方法来实现各种各样的自定义 Logger 组件，但是为什么也可以直接 `log.Print*` 等方法呢？

```
func New(out io.Writer, prefix string, flag int) *Logger
```

其实是在标准库内，如果你刚刚细心的看了前面的小节，不难发现其默认实现了一个 Logger 组件

```
var std = New(os.Stderr, "", LstdFlags)
```

这也是一个小小的精妙之处 ⭕️

## 总结

通过查阅 log 标准库的源码，可得知最简单的一个日志包应该如何编写。另外 log 包是在所有涉及到 Logger 的地方都对 `sync.Mutex` 进行操作（以此解决原子问题），其余逻辑均为组装日志信息和转换数值格式，该包较为经典，可以多读几遍 😄

## 问题

为什么在调用 `runtime.Caller` 前要先解锁，后再加锁呢?


================================================
FILE: content/posts/go/pkg/2018-12-04-fmt.md
================================================
---

title:      "fmt 标准库 --- Print* 是怎么样输出的？"
date:       2018-12-04 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

## 前言

```
package main

import (
	"fmt"
)

func main() {
	fmt.Println("Hello World!")
}
```

标准开场见多了，那内部标准库又是怎么输出这段英文的呢？今天一起来围观下源码吧 🤭

## 原型


```
func Print(a ...interface{}) (n int, err error) {
	return Fprint(os.Stdout, a...)
}

func Println(a ...interface{}) (n int, err error) {
	return Fprintln(os.Stdout, a...)
}

func Printf(format string, a ...interface{}) (n int, err error) {
	return Fprintf(os.Stdout, format, a...)
}
```

- Print：使用默认格式说明符打印格式并写入标准输出。当两者都不是字符串时，在操作数之间添加空格
- Println：同上，不同的地方是始终在操作数之间添加空格，并附加换行符
- Printf：根据格式说明符进行格式化并写入标准输出

以上三类就是最常见的格式化 I/O 的方法，我们将基于此去进行拆解描述

## 执行流程

### 案例一：Print

在这里我们使用 `Print` 方法做一个分析，便于后面的加深理解 😄

```
func Print(a ...interface{}) (n int, err error) {
	return Fprint(os.Stdout, a...)
}
```

`Print` 使用默认格式说明符打印格式并写入标准输出。另外当两者都为非空字符串时将插入一个空格

#### 原型

```
func Fprint(w io.Writer, a ...interface{}) (n int, err error) {
	p := newPrinter()
	p.doPrint(a)
	n, err = w.Write(p.buf)
	p.free()
	return
}
```

该函数一共有两个形参：

- w：输出流，只要实现 io.Writer 就可以（抽象）为流的写入
- a：任意类型的多个值

#### 分析主干流程

1、 p := newPrinter(): 申请一个临时对象池（sync.Pool）

```
var ppFree = sync.Pool{
	New: func() interface{} { return new(pp) },
}

func newPrinter() *pp {
	p := ppFree.Get().(*pp)
	p.panicking = false
	p.erroring = false
	p.fmt.init(&p.buf)
	return p
}
```

- ppFree.Get()：基于 sync.Pool 实现 *pp 的临时对象池，每次获取一定会返回一个新的 pp 对象用于接下来的处理
- *pp.panicking：用于解决无限递归的 panic、recover 问题，会根据该参数在 catchPanic 及时掐断
- *pp.erroring：用于表示正在处理错误无效的 verb 标识符，主要作用是防止调用 handleMethods 方法
- *pp.fmt.init(&p.buf)：初始化 fmt 配置，会设置 buf 并且清空 fmtFlags 标志位

2、 p.doPrint(a): 执行约定的格式化动作（参数间增加一个空格、最后一个参数增加换行符）

```
func (p *pp) doPrint(a []interface{}) {
	prevString := false
	for argNum, arg := range a {
	    true && false
		isString := arg != nil && reflect.TypeOf(arg).Kind() == reflect.String
		// Add a space between two non-string arguments.
		if argNum > 0 && !isString && !prevString {
			p.buf.WriteByte(' ')
		}
		p.printArg(arg, 'v')
		prevString = isString
	}
}
```

可以看到底层通过判断该入参，**同时**满足以下条件就会添加分隔符（空格）：

- 当前入参为多个参数（例如：Slice）
- 当前入参不为 nil 且不为字符串（通过反射确定）
- 当前入参不为首项或上一个入参不为字符串

而在 `Print` 方法中，不需要指定格式符。实际上在该方法内直接指定为 `v`。也就是默认格式的值

```
p.printArg(arg, 'v')
```

3. w.Write(p.buf): 写入标准输出（io.Writer）

4. *pp.free(): 释放已缓存的内容。在使用完临时对象后，会将 buf、arg、value 清空再重新存放到 ppFree 中。以便于后面再取出重用（利用 sync.Pool 的临时对象特性）

### 案例二：Printf

#### 标识符

##### Verbs

```
%v	the value in a default format
	when printing structs, the plus flag (%+v) adds field names
%#v	a Go-syntax representation of the value
%T	a Go-syntax representation of the type of the value
%%	a literal percent sign; consumes no value
%t	the word true or false
```

##### Flags

```
+	always print a sign for numeric values;
	guarantee ASCII-only output for %q (%+q)
-	pad with spaces on the right rather than the left (left-justify the field)
#	alternate format: add leading 0 for octal (%#o), 0x for hex (%#x);
	0X for hex (%#X); suppress 0x for %p (%#p);
	for %q, print a raw (backquoted) string if strconv.CanBackquote
	returns true;
	always print a decimal point for %e, %E, %f, %F, %g and %G;
	do not remove trailing zeros for %g and %G;
	write e.g. U+0078 'x' if the character is printable for %U (%#U).
' '	(space) leave a space for elided sign in numbers (% d);
	put spaces between bytes printing strings or slices in hex (% x, % X)
0	pad with leading zeros rather than spaces;
	for numbers, this moves the padding after the sign
```

详细建议参见 [Godoc](https://golang.org/pkg/fmt/#hdr-Printing)

#### 原型

```
func Fprintf(w io.Writer, format string, a ...interface{}) (n int, err error) {
	p := newPrinter()
	p.doPrintf(format, a)
	n, err = w.Write(p.buf)
	p.free()
	return
}
```

与 Print 相比，最大的不同就是 doPrintf 方法了。在这里我们来详细看看其代码，如下：

```
func (p *pp) doPrintf(format string, a []interface{}) {
	end := len(format)
	argNum := 0         // we process one argument per non-trivial format
	afterIndex := false // previous item in format was an index like [3].
	p.reordered = false
formatLoop:
	for i := 0; i < end; {
		p.goodArgNum = true
		lasti := i
		for i < end && format[i] != '%' {
			i++
		}
		if i > lasti {
			p.buf.WriteString(format[lasti:i])
		}
		if i >= end {
			// done processing format string
			break
		}

		// Process one verb
		i++

		// Do we have flags?
		p.fmt.clearflags()
	simpleFormat:
		for ; i < end; i++ {
			c := format[i]
			switch c {
			case '#':   //'#'、'0'、'+'、'-'、' '
				...
			default:
				if 'a' <= c && c <= 'z' && argNum < len(a) {
					...
					p.printArg(a[argNum], rune(c))
					argNum++
					i++
					continue formatLoop
				}
				
				break simpleFormat
			}
		}

		// Do we have an explicit argument index?
		argNum, i, afterIndex = p.argNumber(argNum, format, i, len(a))

		// Do we have width?
		if i < end && format[i] == '*' {
			...
		}

		// Do we have precision?
		if i+1 < end && format[i] == '.' {
			...
		}

		if !afterIndex {
			argNum, i, afterIndex = p.argNumber(argNum, format, i, len(a))
		}

		if i >= end {
			p.buf.WriteString(noVerbString)
			break
		}

		...

		switch {
		case verb == '%': // Percent does not absorb operands and ignores f.wid and f.prec.
			p.buf.WriteByte('%')
		case !p.goodArgNum:
			p.badArgNum(verb)
		case argNum >= len(a): // No argument left over to print for the current verb.
			p.missingArg(verb)
		case verb == 'v':
			...
			fallthrough
		default:
			p.printArg(a[argNum], verb)
			argNum++
		}
	}

	if !p.reordered && argNum < len(a) {
		...
	}
}
```

#### 分析主干流程

1. 写入 % 之前的字符内容
2. 如果所有标志位处理完毕（到达字符尾部），则跳出处理逻辑
3. （往后移）跳过 % ，开始处理其他 verb 标志位
4. 清空（重新初始化） fmt 配置
5. 处理一些基础的 verb 标识符（simpleFormat）。如：'#'、'0'、'+'、'-'、' ' 以及**简单的 verbs 标识符（不包含精度、宽度和参数索引）。需要注意的是，若当前字符为简单 verb 标识符。则直接进行处理。完成后会直接后移到下一个字符**。其余标志位则变更 fmt 配置项，便于后续处理
6. 处理参数索引（argument index）
7. 处理参数宽度（width）
8. 处理参数精度（precision）
9. % 之后若不存在 verbs 标识符则返回 `noVerbString`。值为 %!(NOVERB)
10. 处理特殊 verbs 标识符（如：'%%'、'%#v'、'%+v'）、错误情况（如：参数索引指定错误、参数集个数与 verbs 标识符数量不匹配）或进行格式化参数集
11. 常规流程处理完毕

在特殊情况下，若提供的参数集比 verb 标识符多。fmt 将会贪婪检查下去，将多出的参数集以特定的格式输出，如下：

```
fmt.Printf("%d", 1, 2, 3)
// 1%!(EXTRA int=2, int=3)
```

- 约定前缀额外标志：%!(EXTRA
- 当前参数的类型
- 约定格式符：=
- 当前参数的值（默认以 %v 格式化）
- 约定格式符：)

值得注意的是，当指定了参数索引或实际处理的参数小于入参的参数集时，就不会进行贪婪匹配来展示

### 案例三：Println

#### 原型

```
func Fprintln(w io.Writer, a ...interface{}) (n int, err error) {
	p := newPrinter()
	p.doPrintln(a)
	n, err = w.Write(p.buf)
	p.free()
	return
}
```

在这个方法中，最大的区别就是 doPrintln，我们一起来看看，如下：

```
func (p *pp) doPrintln(a []interface{}) {
	for argNum, arg := range a {
		if argNum > 0 {
			p.buf.WriteByte(' ')
		}
		p.printArg(arg, 'v')
	}
	p.buf.WriteByte('\n')
}
```

#### 分析主干流程

- 循环入参的参数集，并以空格分隔
- 格式化当前参数，默认以 `%v` 对参数进行格式化
- 在结尾添加 `\n` 字符


## 如何格式化参数

在上例的执行流程分析中，可以看到格式化参数这一步是在 `p.printArg(arg, verb)` 执行的，我们一起来看看它都做了些什么？

```
func (p *pp) printArg(arg interface{}, verb rune) {
	p.arg = arg
	p.value = reflect.Value{}

	if arg == nil {
		switch verb {
		case 'T', 'v':
			p.fmt.padString(nilAngleString)
		default:
			p.badVerb(verb)
		}
		return
	}

	switch verb {
	case 'T':
		p.fmt.fmt_s(reflect.TypeOf(arg).String())
		return
	case 'p':
		p.fmtPointer(reflect.ValueOf(arg), 'p')
		return
	}

	// Some types can be done without reflection.
	switch f := arg.(type) {
	case bool:
		p.fmtBool(f, verb)
	case float32:
		p.fmtFloat(float64(f), 32, verb)
	...
	case reflect.Value:
		if f.IsValid() && f.CanInterface() {
			p.arg = f.Interface()
			if p.handleMethods(verb) {
				return
			}
		}
		p.printValue(f, verb, 0)
	default:
		if !p.handleMethods(verb) {
			p.printValue(reflect.ValueOf(f), verb, 0)
		}
	}
}
```

在小节代码中可以看见，fmt 本身对不同的类型做了不同的处理。这样子就避免了通过反射确定。相对的提高了性能

其中有两个特殊的方法，分别是 `handleMethods` 和 `badVerb`，接下来分别来看看他们的作用是什么

1、badVerb

它主要用于格式化并处理错误的行为。我们可以一起来看看，代码如下：

```
func (p *pp) badVerb(verb rune) {
	p.erroring = true
	p.buf.WriteString(percentBangString)
	p.buf.WriteRune(verb)
	p.buf.WriteByte('(')
	switch {
	case p.arg != nil:
		p.buf.WriteString(reflect.TypeOf(p.arg).String())
		p.buf.WriteByte('=')
		p.printArg(p.arg, 'v')
	...
	default:
		p.buf.WriteString(nilAngleString)
	}
	p.buf.WriteByte(')')
	p.erroring = false
}
```

在处理错误格式化时，我们可以对比以下例子：

```
fmt.Printf("%s", []int64{1, 2, 3})
// [%!s(int64=1) %!s(int64=2) %!s(int64=3)]%
```

在 badVerb 中可以看到错误字符串的处理主要分为以下部分：

- 约定前缀错误标志：%!
- 当前的格式化操作符
- 约定格式符：(
- 当前参数的类型
- 约定格式符：=
- 当前参数的值（默认以 %v 格式化）
- 约定格式符：)

2、handleMethods

```
func (p *pp) handleMethods(verb rune) (handled bool) {
	if p.erroring {
		return
	}
	// Is it a Formatter?
	if formatter, ok := p.arg.(Formatter); ok {
		handled = true
		defer p.catchPanic(p.arg, verb)
		formatter.Format(p, verb)
		return
	}

	// If we're doing Go syntax and the argument knows how to supply it, take care of it now.
	...
	
	return false
}
```

这个方法比较特殊，一般在自定义结构体和未知情况下进行调用。主要流程是：

- 若当前参数为错误 verb 标识符，则直接返回
- 判断是否实现了 Formatter 
- 实现，则利用自定义 Formatter 格式化参数
- 未实现，则最大程度的利用 Go syntax 默认规则去格式化参数

## 拓展

在 fmt 标准库中可以通过自定义结构体来实现方法的自定义，大致如下几种

### fmt.State

```
type State interface {
	Write(b []byte) (n int, err error)

	Width() (wid int, ok bool)

	Precision() (prec int, ok bool)

	Flag(c int) bool
}
```

State 用于获取标志位的状态值，涉及如下：

- Write：将格式化完毕的字符写入缓冲区中，等待下一步处理
- Width：返回宽度信息和是否被设置
- Precision：返回精度信息和是否被设置
- Flag：返回特殊标志符（'#'、'0'、'+'、'-'、' '）是否被设置

### fmt.Formatter

```
type Formatter interface {
	Format(f State, c rune)
}
```

Formatter 用于实现**自定义格式化方法**。可通过在自定义结构体中实现 Format 方法来实现这个目的

另外，可以通过 f 获取到当前标识符的宽度、精度等状态值。c 为 verb 标识符，可以得到其动作是什么

### fmt.Stringer

```
type Stringer interface {
	String() string
}
```

当该对象为 String、Array、Slice 等类型时，将会调用 `String()` 方法对类字符串进行格式化

### fmt.GoStringer

```
type GoStringer interface {
	GoString() string
}
```

当格式化特定 verb 标识符（%v）时，将调用 `GoString()` 方法对其进行格式化


## 总结

通过本文对 fmt 标准库的分析，可以发现它有以下特点：

- 在拓展性方面，可以自定义格式化方法等
- 在完整度方面，尽可能的贪婪匹配，输出参数集
- 在性能方面，每种不同的参数类型，都实现了不同的格式化处理操作
- 在性能方面，尽可能的最短匹配，格式化参数集

总的来说，fmt 标准库有许多值得推敲的细节，希望你能够在本文学到 😄


================================================
FILE: content/posts/go/pkg/2018-12-15-unsafe.md
================================================
---

title:      "有点不安全却又一亮的 Go unsafe.Pointer"
date:       2018-12-15 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---


在上一篇文章《深入理解 Go Slice》中，大家会发现其底层数据结构使用了 `unsafe.Pointer`。因此想着再介绍一下其关联知识

## 前言

在大家学习 Go 的时候，肯定都学过 “Go 的指针是不支持指针运算和转换” 这个知识点。为什么呢？

首先，Go 是一门静态语言，所有的变量都必须为标量类型。不同的类型不能够进行赋值、计算等跨类型的操作。那么指针也对应着相对的类型，也在 Compile 的静态类型检查的范围内。同时静态语言，也称为强类型。也就是一旦定义了，就不能再改变它

## 错误示例

```
func main(){
	num := 5
	numPointer := &num

	flnum := (*float32)(numPointer)
	fmt.Println(flnum)
}
```

输出结果：

```
# command-line-arguments
...: cannot convert numPointer (type *int) to type *float32
```

在示例中，我们创建了一个 `num` 变量，值为 5，类型为 `int`。取了其对于的指针地址后，试图强制转换为 `*float32`，结果失败...

## unsafe

针对刚刚的 “错误示例”，我们可以采用今天的男主角 `unsafe` 标准库来解决。它是一个神奇的包，在官方的诠释中，有如下概述：

- 围绕 Go 程序内存安全及类型的操作
- 很可能会是不可移植的
- 不受 Go 1 兼容性指南的保护

简单来讲就是，不怎么推荐你使用。因为它是 unsafe（不安全的），但是在特殊的场景下，使用了它。可以打破 Go 的类型和内存安全机制，让你获得眼前一亮的惊喜效果 😄

### Pointer

为了解决这个问题，需要用到 `unsafe.Pointer`。它表示任意类型且可寻址的指针值，可以在不同的指针类型之间进行转换（类似 C 语言的 void * 的用途）

其包含四种核心操作：

- 任何类型的指针值都可以转换为 Pointer
- Pointer 可以转换为任何类型的指针值
- uintptr 可以转换为 Pointer
- Pointer 可以转换为 uintptr

在这一部分，重点看第一点、第二点。你再想想怎么修改 “错误示例” 让它运行起来？

```
func main(){
	num := 5
	numPointer := &num

	flnum := (*float32)(unsafe.Pointer(numPointer))
	fmt.Println(flnum)
}
```

输出结果：

```
0xc4200140b0
```

在上述代码中，我们小加改动。通过 `unsafe.Pointer` 的特性对该指针变量进行了修改，就可以完成任意类型（*T）的指针转换

需要注意的是，这时还无法对变量进行操作或访问。因为不知道该指针地址指向的东西具体是什么类型。不知道是什么类型，又如何进行解析呢。无法解析也就自然无法对其变更了

### Offsetof

在上小节中，我们对普通的指针变量进行了修改。那么它是否能做更复杂一点的事呢？

```
type Num struct{
	i string
	j int64
}

func main(){
	n := Num{i: "EDDYCJY", j: 1}
	nPointer := unsafe.Pointer(&n)

	niPointer := (*string)(unsafe.Pointer(nPointer))
	*niPointer = "煎鱼"

	njPointer := (*int64)(unsafe.Pointer(uintptr(nPointer) + unsafe.Offsetof(n.j)))
	*njPointer = 2

	fmt.Printf("n.i: %s, n.j: %d", n.i, n.j)
}

```

输出结果：

```
n.i: 煎鱼, n.j: 2
```

在剖析这段代码做了什么事之前，我们需要了解结构体的一些基本概念：

- 结构体的成员变量在内存存储上是一段连续的内存
- 结构体的初始地址就是第一个成员变量的内存地址
- 基于结构体的成员地址去计算偏移量。就能够得出其他成员变量的内存地址

再回来看看上述代码，得出执行流程：

- 修改 `n.i` 值：`i` 为第一个成员变量。因此不需要进行偏移量计算，直接取出指针后转换为 `Pointer`，再强制转换为字符串类型的指针值即可

- 修改 `n.j` 值：`j` 为第二个成员变量。需要进行偏移量计算，才可以对其内存地址进行修改。在进行了偏移运算后，当前地址已经指向第二个成员变量。接着重复转换赋值即可


需要注意的是，这里使用了如下方法（来完成偏移计算的目标）：

1、uintptr：`uintptr` 是 Go 的内置类型。返回无符号整数，可存储一个完整的地址。后续常用于指针运算

```
type uintptr uintptr
```

2、unsafe.Offsetof：返回成员变量 x 在结构体当中的偏移量。更具体的讲，就是返回结构体初始位置到 x 之间的字节数。需要注意的是入参 `ArbitraryType` 表示任意类型，并非定义的 `int`。它实际作用是一个占位符

```
func Offsetof(x ArbitraryType) uintptr
```

在这一部分，其实就是巧用了 `Pointer` 的第三、第四点特性。这时候就已经可以对变量进行操作了 😄

### 错误示例

```
func main(){
	n := Num{i: "EDDYCJY", j: 1}
	nPointer := unsafe.Pointer(&n)
    ...

	ptr := uintptr(nPointer)
	njPointer := (*int64)(unsafe.Pointer(ptr + unsafe.Offsetof(n.j)))
	...
}
```

这里存在一个问题，`uintptr` 类型是不能存储在临时变量中的。因为从 GC 的角度来看，`uintptr` 类型的临时变量只是一个无符号整数，并不知道它是一个指针地址

因此当满足一定条件后，`ptr` 这个临时变量是可能被垃圾回收掉的，那么接下来的内存操作，岂不成迷？

## 总结

简洁回顾两个知识点。第一是 `unsafe.Pointer` 可以让你的变量在不同的指针类型转来转去，也就是表示为任意可寻址的指针类型。第二是 `uintptr` 常用于与 `unsafe.Pointer` 打配合，用于做指针运算，巧妙地很

最后还是那句，没有特殊必要的话。是不建议使用 `unsafe` 标准库，它并不安全。虽然它常常能让你眼前一亮 👌


================================================
FILE: content/posts/go/plugin.md
================================================
---
title: "Go 插件系统，一个凉了快半截的特性？"
date: 2021-12-31T12:54:59+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在 Go 语言中，有一个好像很好用，但却比较少人提及的功能，那就是 Go Plugin。目前在 Go 工程中普遍还没广泛的使用起来，覆盖率不高。

前段时间小咸鱼的同事问了他这玩具怎么用，他正想甩出一个链接，但发现...煎鱼竟然没写过，这不，Go 知识板块的文章地图得补全。

今天煎鱼就大家一起学习 Go Plugin！

## 是什么

Go Team 最早在 Go1.7 实验，在 Go1.8 正式引入了 Go Plugin 的机制。于 2016 年发布，一开始仅支持 Linux 实现：

![](https://files.mdnice.com/user/3610/9a791ced-39db-4f09-a027-60569ccc95dd.png)

Go Plugin 机制实现了 Go 插件的加载和符号解析，能够支持将我们所编写的 Go 包编译为共享库（.so）。

这样 Go 工程就可以加载所编译好的 Go Plugin（已经变成了共享库文件），在程序中调用共享库中的函数、常量、变量等使用。也称其为 Go 语言中的热插拔的插件系统。

截止 Go1.17 为止，Go Plugin 仅支持在 Linux、FreeBSD 和 MacOS 上运行，还不支持 Windows。

## 为什么需要

Go 语言是静态语言，正常我们写一个程序，分如下两个角度来看：
- 从代码编写的角度来看：我们在程序编写的时候就已经把所有的功能实现给确定了，不会发生什么根本性的变化。
- 从程序的角度来看：在 Go 进行编译时，就已经把所有引用的标准库、第三方库等都编译打包好进二进制文件了，因此也就无法在运行时去动态加载，所以没法有其它的可能性。

那么为什么需要 Go Plugin 呢，原因如下：
- 可插拔的插件：程序能够随时的安装插件，也能够卸载他，获得更多运行时的自定义能力。
- 可动态加载运行时模块：随时安装了插件，自然也就需要可自行决定运行哪个插件的模块了。
- 可独立开发插件、模块：主系统和子插件，可能由不同的团队开发和提供，也更有价值。

其实本质上还是**希望程序能够在运行时实现动态的外部加载**，根据不同的条件、场景加载不同的插件功能。

## 使用方法

### 通用概念

Go 官方给出的例子非常简单，只需要在 Go 编译时指定为插件就可以了。

编译的命令例子如下：

```golang
go build -buildmode=plugin
```

当一个插件初次被打开时，所有尚未成为程序一部分的包的init函数被调用。不过主函数不被运行。需要注意**一个插件只会被初始化一次，插件不能被关闭**。

其共有如下几个 API：

```golang
type Plugin
    func Open(path string) (*Plugin, error)
    func (p *Plugin) Lookup(symName string) (Symbol, error)
type Symbol
```
- Plugin.Open：开启一个 Go 插件。如果一个路径已经被打开，那么将返回现有的 `*Plugin`。
- Plugin.Lookup：在插件中搜索名所传入的符号，符号是任何导出的变量或函数。如果没有找到该符号，它会报告一个错误。

主要就是细分为插件和符号，符号（Symbol）本身是一个 interface，在调用 Plugin 相关方法后还是需要进一步断言才能使用。

### 实际编写

了解基本定义后，我们定义一个插件，一般我们会有个 plugins/ 的目录，作为主程序的附属插件集。

插件的代码如下：

```golang
package main

import "fmt"

var V int

func F() {
	fmt.Printf("脑子进了 %d 次煎鱼 \n", V)
}
```

包名必须为 main，在该插件根目录运行： 

```golang
go build -buildmode=plugin -o plugin.so main.go
```

就可以看到在编译的目录下多出了 `plugin.so` 文件，这就是这个插件经过编译后的动态库 .so 文件。

随后只需在主程序加载这个插件就可以了，如下：

```golang
import (
	"plugin"
)

func main() {
	p, err := plugin.Open("plugin.so")
	if err != nil {
		panic(err)
	}
	v, err := p.Lookup("V")
	if err != nil {
		panic(err)
	}
	f, err := p.Lookup("F")
	if err != nil {
		panic(err)
	}

	*v.(*int) = 999
	f.(func())()
}
```

输出结果：

```
脑子进了 999 次煎鱼 
```

在程序中，我们先调用了 `plugin.Open` 方法打开了前面所编译的 `plugin.so` 动态库。

紧接着调用 `plugin.Lookup` 方法，定位到了变量 V 和 方法 F，但由于其返回值都是 Symbol（interface），因此我们需要对其进行类型断言，随时才可以调用和使用。

至此完成了一个插件的基本使用。

## 为什么不被需要

在前面我们提到了大量 Go Plugin 的优点，也演示了其 Plugin 代码编写起来有多么的简单和方便。

但，**为什么 Go Plugin 已经发布了 4 年依然没有被大规模应用**，甚至对于不少业务开发来讲是不被需要的呢，或是压根不知道有这东西？

究其原因，我个人认为一个东西的广泛应用要至少符合以下三大点：
- 基数：需要的场景多。
- 上手：方便且易用。
- 质量：没有大问题。

比较折腾的人的是，Go Plugin 这三大点都欠一些火候，综合导致了该功能的没有大规模应用。

像是要应用 Go Plugin 有诸如下约束：

- 环境问题：不支持 Windows 等（暂无计划，#19282），MacOS 有些问题，一开始只支持 Linux，其他的也是后面慢慢增加的支持。
- Go 版本问题：Plugin 构建环境和第三方包的依赖版本需要保持一致。
- 特性问题：Plugin 特性的缺失，例如不支持插件的关闭，暂时无新计划支持（#20461）。

## 总结

在 Go issues 中畅游时，能看到许多小伙伴在以往 4 年踩过的坑和无奈。甚至有一个高赞回答（#19282）表示：**插件功能主要是一个技术演示，由于一些不道德的原因，被作为语言的稳定功能发布**（The plugin feature is mostly a tech demo that for some unholy reason got released as a stable feature of the language.）。

目前 Go Plugin 并不是 Go Team 的优先事项，在 Windows/Mac 的支持存在问题。GOPATH 有问题，不同 GO 版本也有问题。更是建议如果您想要插件，请走较慢的 grpc 路线，因为它们是有效的插件。

也可以参考为数不多的一些 Go Plugin 用户的方案，例如：tidb。

但如果要正式使用，是需要慎重考虑，又或是再等等...等更完善的那一天？

## 参考

- [Go Package plugin](https://golang.org/pkg/plugin/)
- [Why is there no windows support for plugins?](https://www.reddit.com/r/golang/comments/bsoa4e/why_is_there_no_windows_support_for_plugins/)
- [plugin: add Windows support](https://github.com/golang/go/issues/19282)
- [plugin: Add support for closing plugins](https://github.com/golang/go/issues/20461)
- [如何评价 Go 标准库中新增的 plugin 包？](https://www.zhihu.com/question/51650593)
- [一文搞懂Go语言的plugin](https://mp.weixin.qq.com/s/yBosg0q0V_-wYk9G2GiVTw)

================================================
FILE: content/posts/go/real-context.md
================================================
---
title: "分享 Go 使用 Context 的正式姿势"
date: 2021-12-31T12:54:54+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在 Go 语言中，Goroutine（协程），也就是关键字 `go` 是一个家喻户晓的高级用法。这起的非常妙，说到 Go，就会想到这一门语言，想到 goroutine 这一关键字，而与之关联最深的就是 context。

![](https://files.mdnice.com/user/3610/2f26bd64-e9bd-4c89-a9a0-326b8c2b9d00.png)

## 背景

平时在 Go 工程中开发中，几乎所有服务端（例如：HTTP Server）的默认实现，都在处理请求时新起 goroutine 进行处理。

但一开始存在一个问题，那就是当一个请求被取消或超时时，所有在该请求上工作的 goroutines 应该迅速退出，以便系统可以回收他们正在使用的任何资源。

当年可没有 context 标准库。很折腾。因此 Go 官方在 2014 年正式宣发了 context 标准库，形成一个完整的闭环。

但有了 context 标准库，Go 爱好者们又奇怪了，前段时间我就被问到了：“Go context 的正确使用姿势是怎么样的”？

（一张忘记在哪里被问的隐形截图）

今天这篇文章就由煎鱼带你看看。

## Context 用法

在 Go context 用法中，我们常常将其与 select 关键字结合使用，用于监听其是否结束、取消等。

代码如下：

```golang
const shortDuration = 1 * time.Millisecond

func main() {
	ctx, cancel := context.WithTimeout(context.Background(), shortDuration)
	defer cancel()

	select {
	case <-time.After(1 * time.Second):
		fmt.Println("脑子进煎鱼了")
	case <-ctx.Done():
		fmt.Println(ctx.Err())
	}
}
```

输出结果：

```
context deadline exceeded
```

如果是更进一步结合 goroutine 的话，常见的例子是：

```golang
	func(ctx context.Context) <-chan int {
		dst := make(chan int)
		n := 1
		go func() {
			for {
				select {
				case <-ctx.Done():
					return
				case dst <- n:
					n++
				}
			}
		}()
		return dst
	}
```

我们平时工程中会起很多的 goroutine，这时候会在 goroutine 内结合 for+select，针对 context 的事件进行处理，达到跨 goroutine 控制的目的。

## 正确的使用姿势

### 对第三方调用要传入 context

在 Go 语言中，Context 的默认支持已经是约定俗称的规范了。因此在我们对第三方有调用诉求的时候，要传入 context：

```golang
func main() {
	req, err := http.NewRequest("GET", "https://eddycjy.com/", nil)
	if err != nil {
		fmt.Printf("http.NewRequest err: %+v", err)
		return
	}

	ctx, cancel := context.WithTimeout(req.Context(), 50*time.Millisecond)
	defer cancel()

	req = req.WithContext(ctx)
	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		fmt.Printf("http.DefaultClient.Do err: %+v", err)
		return
	}
	defer resp.Body.Close()
}
```

这样子由于第三方开源库已经实现了根据 context 的超时控制，那么当你所传入的时间到达时，将会中断调用。

若你发现第三方开源库没支持 context，那建议赶紧跑，换一个。免得在微服务体系下出现级联故障，还没有简单的手段控制，那就很麻烦了。

### 不要将上下文存储在结构类型中

大家会发现，在 Go 语言中，所有的第三方开源库，业务代码。清一色的都会将 context 放在方法的一个入参参数，作为首位形参。

例如：

![](https://files.mdnice.com/user/3610/f79303b3-2070-4d2b-ac6b-840c413d03fd.png)

标准要求：每个方法的第一个参数都将 context 作为第一个参数，并使用 ctx 变量名惯用语。

当然，我们也不能一杆子打死所有情况。确实存在极少数是把 context 放在结构体中的。基本常见于：
- 底层基础库。
- DDD 结构。

每个请求都是独立的，context 自然每个都不一样，想清楚自己的应用使用场景很重要，否则遵循 Go 基本规范就好。


在真实案例来看，有的 Leader 会单纯为了不想频繁传 context 而设计成结构体，结果导致一线 RD 就得天天 NewXXX，甚至有时候忘记了，还得背个小锅。

### 函数调用链必须传播上下文

我们会把 context 作为方法首位，本质目的是为了传播 context，自行完整调用链路上的各类控制：

```golang
func List(ctx context.Context, db *sqlx.DB) ([]User, error) {
	ctx, span := trace.StartSpan(ctx, "internal.user.List")
	defer span.End()

	users := []User{}
	const q = `SELECT * FROM users`

	if err := db.SelectContext(ctx, &users, q); err != nil {
		return nil, errors.Wrap(err, "selecting users")
	}

	return users, nil
}
```

像在上述例子中，我们会把所传入方法的 context 一层层的传进去下一级方法。这里就是将外部的 context 传入 List 方法，再传入 SQL 执行的方法，解决了 SQL 执行语句的时间问题。

### context 的继承和派生

在 Go 标准库 context 中具有以下派生 context 的标准方法：

```golang
func WithCancel(parent Context) (ctx Context, cancel CancelFunc)
func WithDeadline(parent Context, d time.Time) (Context, CancelFunc)
func WithTimeout(parent Context, timeout time.Duration) (Context, CancelFunc)
```

代码例子如下：

```golang
func handle(w http.ResponseWriter, req *http.Request) {
  // parent context
	timeout, _ := time.ParseDuration(req.FormValue("timeout"))
	ctx, cancel := context.WithTimeout(context.Background(), timeout)

  // chidren context
	newCtx, cancel := context.WithCancel(ctx)
	defer cancel()
	// do something...
}
```

一般会有父级 context 和子级 context 的区别，我们要保证在程序的行为中上下文对于多个 goroutine 同时使用是安全的。并且存在父子级别关系，父级 context 关闭或超时，可以继而影响到子级 context 的程序。

### 不传递 nil context

很多时候我们在创建 context 时，还不知道其具体的作用和下一步用途是什么。

这种时候大家可能会直接使用 `context.Background` 方法：

```golang
var (
   background = new(emptyCtx)
   todo       = new(emptyCtx)
)

func Background() Context {
   return background
}

func TODO() Context {
   return todo
}
```

但在实际的 context 建议中，我们会建议使用 `context.TODO` 方法来创建顶级的 context，直到弄清楚实际 Context 的下一步用途，再进行变更。

### context 仅传递必要的值

我们在使用 context 作为上下文时，经常有信息传递的诉求。像是在 gRPC 中就会有 metadata 的概念，而在 gin 中就会自己封装 context 作为参数管理。

Go 标准库 context 也有提供相关的方法：

```golang
type Context
    func WithValue(parent Context, key, val interface{}) Context
```

代码例子如下：

```golang
func main() {
	type favContextKey string
	f := func(ctx context.Context, k favContextKey) {
		if v := ctx.Value(k); v != nil {
			fmt.Println("found value:", v)
			return
		}
		fmt.Println("key not found:", k)
	}

	k := favContextKey("脑子进")
	ctx := context.WithValue(context.Background(), k, "煎鱼")

	f(ctx, k)
	f(ctx, favContextKey("小咸鱼"))
}
```

输出结果：

```
found value: 煎鱼
key not found: 小咸鱼
```

在规范中，我们建议 context 在传递时，仅携带必要的参数给予其他的方法，或是 goroutine。甚至在 gRPC 中会做严格的出、入上下文参数的控制。

在业务场景上，context 传值适用于传必要的业务核心属性，例如：租户号、小程序ID 等。不要将可选参数放到 context 中，否则可能会一团糟。

## 总结

- 对第三方调用要传入 context，用于控制远程调用。
- 不要将上下文存储在结构类型中，尽可能的作为函数第一位形参传入。
- 函数调用链必须传播上下文，实现完整链路上的控制。
- context 的继承和派生，保证父、子级 context 的联动。
- 不传递 nil context，不确定的 context 应当使用 TODO。
- context 仅传递必要的值，不要让可选参数揉在一起。

================================================
FILE: content/posts/go/reflect.md
================================================
---
title: "解密 Go 语言之反射 reflect"
date: 2020-11-07T15:01:51+08:00
draft: false
toc: true
images:
tags: 
  - go
  - 深度解密
---

大家好，我是煎鱼。

在所有的语言中，反射这一功能基本属于必不可少的模块。虽说 “反射” 这个词让人根深蒂固，但更多的还是 WHY。反射到底是什么，反射又是基于什么法则实现的？

![image](https://image.eddycjy.com/47976eb32b9cb5bdbe1869123fefb92b.jpg)

今天我们通过这篇文章来一一揭晓，以 Go 语言为例，了解反射到底为何物，其底层又是如何实现的。

## 反射是什么

在计算机学中，反射是指计算机程序在运行时（runtime）可以访问、检测和修改它本身状态或行为的一种能力。用比喻来说，反射就是程序在运行的时候能够 “观察” 并且修改自己的行为（来自维基百科）。

![image](https://image.eddycjy.com/96394a2bb7b1dd964b5197837781e348.jpg)

简单来讲就是，应用程序能够在运行时观察到变量的值，并且能够修改他。

## 一个例子

最常见的 reflect 标准库例子，如下：

```
import (
	"fmt"
	"reflect"
)

func main() {
	rv := []interface{}{"hi", 42, func() {}}
	for _, v := range rv {
		switch v := reflect.ValueOf(v); v.Kind() {
		case reflect.String:
			fmt.Println(v.String())
		case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
			fmt.Println(v.Int())
		default:
			fmt.Printf("unhandled kind %s", v.Kind())
		}
	}
}
```

输出结果：

```
hi
42
unhandled kind func
```

在程序中主要是声明了 rv 变量，变量类型为 `interface{}`，其包含 3 个不同类型的值，分别是字符串、数字、闭包。一般 `interface{}` 的使用常见于不知道入参者具体的基本类型是什么，那么就会用 `interface{}` 类型来做一个伪 “泛型”。

这时候又会引出一个新的问题，既然入参是 `interface{}`，那么出参时呢？ Go 语言是强类型语言，入参是 `interface{}`，出参也肯定是跑不了的，因此必然离不开类型的判断，这时候就要用到反射，也就是 reflect 标准库。反射过后又再进行 `(type)` 的类型断言。

![image](https://image.eddycjy.com/f14d599ca1763d6e33e98179474929ac.jpg)

这就是我们在编写程序时最常遇见的一个反射使用场景。

## Go reflect

reflect 标准库中，最核心的莫过于 `reflect.Type` 和 `reflect.Value` 类型。而在反射中所使用的方法都围绕着这两者进行，其方法主要含义如下：

![image](https://image.eddycjy.com/da4e21e579da2a049598c5e209209269.jpg)

- `TypeOf` 方法：用于提取入参值的**类型信息**。

- `ValueOf` 方法：用于提取存储的变量的**值信息**。

### reflect.TypeOf

演示程序：

```
func main() {
	blog := Blog{"煎鱼"}
	typeof := reflect.TypeOf(blog)
	fmt.Println(typeof.String())
}
```

输出结果：

```
main.Blog
```

从输出结果中可得出 `reflect.TypeOf` 成功解析出 `blog` 变量的类型是 `main.Blog`，也就是连 package 都知道了。通过人识别的角度来看似乎很正常，但程序就不是这样了。

他是怎么知道 “他” 是哪个 package 下的什么呢？我们一起追一下源码看看：

```
func TypeOf(i interface{}) Type {
	eface := *(*emptyInterface)(unsafe.Pointer(&i))
	return toType(eface.typ)
}
```

从源码层面来看，`TypeOf` 方法中主要涉及三块操作，分别如下：

1. 使用 `unsafe.Pointer` 方法获取任意类型且可寻址的指针值。

2. 利用 `emptyInterface` 类型进行强制的 `interface` 类型转换。

3. 调用 `toType` 方法转换为可供外部使用的 `Type` 类型。

而这之中信息量最大的是 `emptyInterface` 结构体中的 `rtype` 类型：

```
type rtype struct {
	size       uintptr
	ptrdata    uintptr 
	hash       uint32 
	tflag      tflag 
	align      uint8  
	fieldAlign uint8  
	kind       uint8   
	equal     func(unsafe.Pointer, unsafe.Pointer) bool
	gcdata    *byte  
	str       nameOff 
	ptrToThis typeOff 
}
```

在使用上最重要的是 `rtype` 类型，其实现了 `Type` 类型的所有接口方法，因此他可以直接作为 `Type` 类型返回，而 `Type` 实际上是一个接口实现，其包含了获取一个类型所必要的所有方法：

```
type Type interface {
	// 适用于所有类型
	// 返回该类型内存对齐后所占用的字节数
	Align() int

	// 仅作用于 strcut 类型
	// 返回该类型内存对齐后所占用的字节数
	FieldAlign() int

	// 返回该类型的方法集中的第 i 个方法
	Method(int) Method

	// 根据方法名获取对应方法集中的方法
	MethodByName(string) (Method, bool)

	// 返回该类型的方法集中导出的方法的数量。
	NumMethod() int

	// 返回该类型的名称
	Name() string
	...
}
```

`Type` 接口的方法是真的多，建议大致过一遍，了解清楚有哪些方法，再针对向看就好。

主体思想是给自己大脑建立一个索引，便于后续快速到 pkg.go.dev 上查询。

### reflect.ValueOf

演示程序：

```
func main() {
	var x float64 = 3.4
	fmt.Println("value:", reflect.ValueOf(x))
}
```

输出结果：

```
value: 3.4
```

从输出结果中可得知通过 `reflect.ValueOf` 成功获取到了变量 `x` 的值为 3.4。与 `reflect.TypeOf` 形成一个相匹配，一个负责获取类型，一个负责获取值。

那么 `reflect.ValueOf` 是怎么获取到值的呢，核心源码如下：

```
func ValueOf(i interface{}) Value {
	if i == nil {
		return Value{}
	}

	escapes(i)

	return unpackEface(i)
}

func unpackEface(i interface{}) Value {
	e := (*emptyInterface)(unsafe.Pointer(&i))
	t := e.typ
	if t == nil {
		return Value{}
	}
	f := flag(t.Kind())
	if ifaceIndir(t) {
		f |= flagIndir
	}
	return Value{t, e.word, f}
}
```

从源码层面来看，`ValueOf` 方法中主要涉及如下几个操作：

1. 调用 `escapes` 让变量 `i` 逃逸到堆上。

2. 将变量 `i` 强制转换为 `emptyInterface` 类型。

3. 将所需的信息（其中包含值的具体类型和指针）组装成 `reflect.Value` 类型后返回。

#### 何时类型转换

在调用 `reflect` 进行一系列反射行为时，Go 又是在什么时候进行的类型转换呢。毕竟我们传入的是 `float64`，而函数如参数是 `inetrface` 类型。

查看汇编如下:

```
$ go tool compile -S main.go                         
	...
	0x0058 00088 ($GOROOT/src/reflect/value.go:2817)	LEAQ	type.float64(SB), CX
	0x005f 00095 ($GOROOT/src/reflect/value.go:2817)	MOVQ	CX, reflect.dummy+8(SB)
	0x0066 00102 ($GOROOT/src/reflect/value.go:2817)	PCDATA	$0, $-2
	0x0066 00102 ($GOROOT/src/reflect/value.go:2817)	CMPL	runtime.writeBarrier(SB), $0
	0x006d 00109 ($GOROOT/src/reflect/value.go:2817)	JNE	357
	0x0073 00115 ($GOROOT/src/reflect/value.go:2817)	MOVQ	AX, reflect.dummy+16(SB)
	0x007a 00122 ($GOROOT/src/reflect/value.go:2348)	PCDATA	$0, $-1
	0x007a 00122 ($GOROOT/src/reflect/value.go:2348)	MOVQ	CX, reflect.i+64(SP)
	0x007f 00127 ($GOROOT/src/reflect/value.go:2348)	MOVQ	AX, reflect.i+72(SP)
	...
```

显然，Go 语言会在编译阶段就会完成分析，且进行类型转换。这样子 `reflect` 真正所使用的就是 `interface` 类型了。

### reflect.Set

演示程序：

```
func main() {
	i := 2.33
	v := reflect.ValueOf(&i)
	v.Elem().SetFloat(6.66)
	log.Println("value: ", i)
}
```

输出结果：

```
value:  6.66

```

从输出结果中，我们可得知在调用 `reflect.ValueOf` 方法后，我们利用 `SetFloat` 方法进行了值变更。核心的方法之一就是 Setter 相关的方法，我们可以一起看看其源码是怎么实现的：

```
func (v Value) Set(x Value) {
	v.mustBeAssignable()
	x.mustBeExported() // do not let unexported x leak
	var target unsafe.Pointer
	if v.kind() == Interface {
		target = v.ptr
	}
	x = x.assignTo("reflect.Set", v.typ, target)
	if x.flag&flagIndir != 0 {
		typedmemmove(v.typ, v.ptr, x.ptr)
	} else {
		*(*unsafe.Pointer)(v.ptr) = x.ptr
	}
}
```

1. 检查反射对象及其字段是否可以被设置。

2. 检查反射对象及其字段是否导出（对外公开）。

3. 调用 `assignTo` 方法创建一个新的反射对象并对原本的反射对象进行覆盖。

4. 根据 `assignTo` 方法所返回的指针值，对当前反射对象的指针进行值的修改。

简单来讲就是，检查是否可以设置，接着创建一个新的对象，最后对其修改。是一个非常标准的赋值流程。

## 反射三大定律

Go 语言中的反射，其归根究底都是在实现三大定律：

1. Reflection goes from interface value to reflection object.

2. Reflection goes from reflection object to interface value.

3. To modify a reflection object, the value must be settable.

我们将针对这核心的三大定律进行介绍和说明，以此来理解 Go 反射里的各种方法是基于什么理念实现的。

### 第一定律 

反射的第一定律是：“反射可以从接口值（interface）得到反射对象”。

示例代码：


```
func main() {
	var x float64 = 3.4
	fmt.Println("type:", reflect.TypeOf(x))
}
```

输出结果：

```
type: float64
```

可能有读者就迷糊了，我明明在代码中传入的变量 `x`，他的类型是 `float64`。怎么就成从接口值得到反射对象了。

其实不然，虽然在代码中我们所传入的变量基本类型是 `float64`，但是 `reflect.TypeOf` 方法入参是 `interface{}`，本质上 Go 语言内部对其是做了类型转换的。这一块会在后面会进一步展开说明。

### 第二定律

反射的第二定律是：“可以从反射对象得到接口值（interface）”。其与第一条定律是相反的定律，可以是互相补充了。

示例代码：

```
func main() {
	vo := reflect.ValueOf(3.4)
	vf := vo.Interface().(float64)
	log.Println("value:", vf)
}
```

输出结果：

```
value: 3.4
```

可以看到在示例代码中，变量 `vo` 已经是反射对象，然后我们可以利用其所提供的的 `Interface` 方法获取到接口值（interface），并最后强制转换回我们原始的变量类型。

### 第三定律

反射的第三定律是：“要修改反射对象，该值必须可以修改”。第三条定律看上去与第一、第二条均无直接关联，但却是必不可少的，因为反射在工程实践中，目的一就是可以获取到值和类型，其二就是要能够修改他的值。

否则反射出来只能看，不能动，就会造成这个反射很鸡肋。例如：应用程序中的配置热更新，必然会涉及配置项相关的变量变动，大多会使用到反射来变动初始值。

示例代码：

```
func main() {
	i := 2.33
	v := reflect.ValueOf(&i)
	v.Elem().SetFloat(6.66)
	log.Println("value: ", i)
}
```

输出结果：

```
value:  6.66
```

单从结果来看，变量 `i` 的值确实从 `2.33` 变成了 `6.66`，似乎非常完美。

但是单看代码，似乎有些 “问题”，怎么设置一个反射值这么 ”麻烦“：

1. 为什么必须传入变量 `i` 的指针引用？

2. 为什么变量 `v` 在设置前还需要 `Elem` 一下？

本叛逆的 Gophper 表示我就不这么设置，行不行呢，会不会出现什么问题：

```
func main() {
	i := 2.33
	reflect.ValueOf(i).SetFloat(6.66)
	log.Println("value: ", i)
}
```

报错信息：

```
panic: reflect: reflect.Value.SetFloat using unaddressable value

goroutine 1 [running]:
reflect.flag.mustBeAssignableSlow(0x8e)
        /usr/local/Cellar/go/1.15/libexec/src/reflect/value.go:259 +0x138
reflect.flag.mustBeAssignable(...)
        /usr/local/Cellar/go/1.15/libexec/src/reflect/value.go:246
reflect.Value.SetFloat(0x10b2980, 0xc00001a0b0, 0x8e, 0x401aa3d70a3d70a4)
        /usr/local/Cellar/go/1.15/libexec/src/reflect/value.go:1609 +0x37
main.main()
        /Users/eddycjy/go-application/awesomeProject/main.go:10 +0xc5
```

根据上述提示可知，由于使用 “使用不可寻址的值”，因此示例程序无法正常的运作下去。并且这是一个 `reflect` 标准库本身就加以防范了的硬性要求。

这么做的原因在于，Go 语言的函数调用的传递都是值拷贝的，因此若不传指针引用，单纯值传递，那么肯定是无法变动反射对象的源值的。因此 Go 标准库就对其进行了逻辑判断，避免出现问题。

因此期望变更反射对象的源值时，我们必须主动传入对应变量的指针引用，并且调用 `reflect` 标准库的 `Elem` 方法来获取指针所指向的源变量，并且最后调用 `Set` 相关方法来进行设置。 

## 总结

通过本文我们学习并了解了 Go 反射是如何使用，又是基于什么定律设计的。另外我们稍加关注，不难发现 Go 的反射都是基于接口（interface）来实现的，更进一步来讲，Go 语言中运行时的功能很多都是基于接口来实现的。

整体来讲，Go 反射是围绕着三者进行的，分别是 Type、Value 以及 Interface，三者相辅相成，而反射本质上与 Interface​ 存在直接关系，Interface​ 这一块的内容我们也将在后续的文章进行进一步的剖析。


================================================
FILE: content/posts/go/runtimepark.md
================================================
---
title: "Goroutine 一泄露就看到他，这是个什么？"
date: 2021-12-31T12:55:01+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

作为一个 Go 语言的使用大户，常常就有人冷不丁的，一下就泄露了...泄露了啥？

表象来看当然是 goroutine 泄露了，这时候就会有小伙伴开始跑去拉取 PProf。就会看到类似下面这张图：

![](https://files.mdnice.com/user/3610/78c8dadf-4f5c-4dfe-be36-d39bfa9d13d3.png)

重点会看到 `runtime.gopark` 这个函数，在所有的 goroutine 泄露中都会看到有，并且都会是大头。

既然是大头，也就会有许多朋友以为他是泄漏点，在那一顿猛查，那这个函数到底是什么，作用是？ 

## runtime.gopark 是何物

想要知道 `runtime.gopark` 函数是作用，最快的办法就是看源码了。其实现细节在 src/runtime/proc.go 文件中。

源代码如下：

```golang
func gopark(unlockf func(*g, unsafe.Pointer) bool, lock unsafe.Pointer, reason waitReason, traceEv byte, traceskip int) {
	mp := acquirem()
	gp := mp.curg
	status := readgstatus(gp)
	mp.waitlock = lock
	mp.waitunlockf = unlockf
	gp.waitreason = reason
	mp.waittraceev = traceEv
	mp.waittraceskip = traceskip
	releasem(mp)
	
	mcall(park_m)
}
```

该函数主要作用有三大点：
- 调用 `acquirem` 函数：
    - 获取当前 goroutine 所绑定的 m，设置各类所需数据。
    - 调用 `releasem` 函数**将当前 goroutine 和其 m 的绑定关系解除**。
- 调用 `park_m` 函数：
    - 将当前 goroutine 的状态从 `_Grunning` 切换为 `_Gwaiting`，也就是等待状态。
    - 删除 m 和当前 goroutine m->curg（简称gp）之间的关联。
- 调用 `mcall` 函数，仅会在需要进行 goroutiine 切换时会被调用：
    - 切换当前线程的堆栈，从 g 的堆栈切换到 g0 的堆栈并调用 fn(g) 函数。
    - 将 g 的当前 PC/SP 保存在 g->sched 中，以便后续调用 goready 函数时可以恢复运行现场。

熟读了其源码后，我们可得知该函数的关键作用就是**将当前的 goroutine 放入等待状态**，这意味着 goroutine 被暂时被搁置了，也就是被运行时调度器暂停了。

## 缘由

回到最初的问题，之所以 goroutine 泄露，你就会看到大量的 `runtime.gopark` 函数，这是因为 goroutine 泄露一般不会单单只是一个 goroutine，肯定是会有多个的。

同时这些 goroutine 在调用了 `runtime.gopark` 函数后都被暂停了，也就是进入休眠状态，自然而然也就停留在此。

直至满足条件后再被 `runtime.goready` 函数唤醒，该函数会将已准备就绪的 goroutine 切换状态，再加入运行队列，等待调度器的新一轮调度。

## 思考

前几天就有读者在我的 Go 读者群中咨询了下述问题，也和  `runtime.gopark` 函数有关。问题如下：

![](https://files.mdnice.com/user/3610/eb5d0483-8193-4adf-881e-490825d137fe.png)

经过上述的分析，显然 `runtime.gopark` 不是 goroutine 的一种状态，导致 goroutine 状态变更只是他的执行过程中所涉及到，产生的一个结果。

而 goroutine 的状态一共有 9 种，有兴趣的小伙伴可以了解。如下：

状态  | 含义
---|---| ---
_Gidle  | 刚刚被分配，还没有进行初始化。
_Grunnable  | 已经在运行队列中，还没有执行用户代码。
_Grunning | 不在运行队列里中，已经可以执行用户代码，此时已经分配了 M 和 P。
_Gsyscall | 正在执行系统调用，此时分配了 M。
_Gwaiting | 在运行时被阻止，没有执行用户代码，也不在运行队列中，此时它正在某处阻塞等待中。
_Gmoribund_unused | 尚未使用，但是在 gdb 中进行了硬编码。
_Gdead | 尚未使用，这个状态可能是刚退出或是刚被初始化，此时它并没有执行用户代码，有可能有也有可能没有分配堆栈。
_Genqueue_unused | 尚未使用。
_Gcopystack | 正在复制堆栈，并没有执行用户代码，也不在运行队列中。

## 总结

在今天这篇文章中，我们介绍了大家最常碰到的 goroutine 泄露，而在泄露后最关心的 `runtime.gopark` 函数的意义，我们从源码再到作用进行了一轮剖析。

下次如果再有人问你 `runtime.gopark` 是干嘛用的，就可以愉快的把这篇文章甩给他，分享你的知识啦 ：）

================================================
FILE: content/posts/go/rust-php.md
================================================
---
title: "Rust 内讧，PHP 主力淡出？Go：好好放假"
date: 2021-12-31T12:55:20+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

现在已经是 2021 年的 Q4 季度了，许多职场人都忙的飞起，被 PPT 各种轰炸。

在上周，看到几门语言的社区都发生了一些大事，煎鱼表示大受震撼，来说几句我的看法。

## PHP 主力淡出

在 11 月 23 日，看到 PHP 的主力开发 [Nikita Popov](https://twitter.com/nikita_ppv "Nikita Popov") 在论坛上发文宣布将**不再以专业身份从事 PHP 工作**，投入到 PHP 开发中的时间将会大幅度减少。

![](https://files.mdnice.com/user/3610/82ba0eaf-fa69-4bee-9cbc-ec385d3b9793.png)

根据 Jetbrains 分享的消息来看，可得知 Nikita Popov 在高中（2011 年）时就开始参与 PHP 开发，截止现在已有 10 年经验了。

![](https://files.mdnice.com/user/3610/93d9d4c9-9863-42fe-9d2c-f5ada62210c2.png)

他离开的原因，我看了一遍帖子，众说纷纭，业内猜测有以下两个观点：
- 迫于生活压力，过多精力投入维护开源项目收入不高。
- PHP 新版本特性受阻等原因，把精力从 PHP 转到 LLVM。

也因此，PHP 社区加速宣布成立 PHP 基金会《[The New Life of PHP – The PHP Foundation](https://blog.jetbrains.com/phpstorm/2021/11/the-php-foundation/ "The New Life of PHP – The PHP Foundation")》。基金会所募集的资金，将会用于资助开发者在 PHP 上工作。

基金会的宣发上，讲的很清楚，为的就是**避免再发生失去 PHP 的主要贡献者**的事情发生，这影响是非常之巨大的。

果然，面包和理想，还是要有权衡，Typora 都开始收费了。

## Rust 社区内讧

在 11 月 22 日，Rust 社区的审核团队集体辞职（Moderation Team Resignation），立即生效。宣布用的 pr 如下图：

![](https://files.mdnice.com/user/3610/a4359504-a128-43e1-9b36-b855307b8825.png)

团队辞职的原因是：**为了抗议 Rust 核心团队将自己置于对任何人都不负责任的地位，只对自己负责**。

一时间，吃瓜众说纷纭。但没有人再给出官方解释了。业内猜测有以下两个观点：
- 在 Rust 运作上：认为与亚马逊正在试图侵蚀 Rust 有关。包括：雇佣了语言团队、编译器团队负责人等。
- 在 Rust 基金会上：亚马逊决定不设立 Rust 基金会 ED，主席将在 Rust 基金会中拥有巨大的权力。

截止 11 月 27 号，这件事感觉已经见不到 “真相” 了。因为 [pr](https://github.com/rust-lang/team/pull/671 "pr") 和 [reddit](https://www.reddit.com/r/rust/comments/qzme1z/moderation_team_resignation/ "reddit") 上的讨论帖均已锁定，没有正式回复。

总感觉有种黑幕的感觉？

## 总结

看了这两起社区重大异常后，再对比看 Go 社区，似乎又比较的温和。毕竟 Go 一开始的诞生，就来源于 Google 大佬们在职期间对既有使用语言的不满。

这么多年了，他们也一直没有离职。Google 也提供了不少的时间和资金给 Go 核心团队做宣传和维护社区，相对安全，还**能定期休假 2 周**（静默期），真是太羡慕了。

但在反面来看，也有很多人嫌弃 Go 背后的靠山是 Google，你怎么看呢？

欢迎在评论区留言和交流：）

================================================
FILE: content/posts/go/site-history.md
================================================
---
title: "分久必合，golang.org 将成为历史！"
date: 2021-12-31T12:55:03+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

这两天看到官方博客的《[Tidying up the Go web experience](https://go.dev/blog/tidy-web "Tidying up the Go web experience")》，已经明确了优化 Go 站点的计划和安排了，为此今天和大家分享这一个好消息。

在之前 Go 官方推出了新的站点 go.dev，一个新的 Go 开发者中心：

![go.dev](https://files.mdnice.com/user/3610/c70f1330-64da-4b65-8988-f9dbe6b1df05.png)

以及提供给开发者查询 Go 包（package）和模块（module）信息的配套网站 pkg.go.dev：

![pkg.go.dev](https://files.mdnice.com/user/3610/41df22df-78e2-4b15-83d7-c8e38fcaba54.png)

看上去似乎美好，但其实原有的 golang.org 在继续提供 Go 发行版下载、文档和标准库的软件包的资料。

而其他 Go 网站，例如：blog.golang.org、play.golang.org、talks.golang.org 以及tour.golang.org，又都拥有额外的 Go 资料。这一切都有些零散和混乱。

在软件发展来讲，这种被称之为 ”绞杀者“ 模式：

![图来自网络](https://files.mdnice.com/user/3610/4645e874-771a-452a-b4ba-e41d8ffe5673.png)

也就是旧系统不断地被新系统取代，在两边都还存在流量时，会保持两边的运行。随着时间的推移，新系统不断地取代老系统，最终完全取代。

Go 官方**计划在接下来的一两个月里，将把 golang.org 网站合并成一个统一的网站**，也就是在 go.dev 上。

所有的现有 URL（例如：Go 标准库、Go 博客等）都会重定向到新的 URL 地址中，不会出现破坏性修改（无法访问），一切按计划都是兼容的。


![](https://files.mdnice.com/user/3610/0708fcf4-90b2-4451-8a3d-5bf5ce2a1dfa.png)


咱们将会有一个更统一的 Go 网站，部分 Go 初学者也不再需要辛辛苦苦再翻山倒海先找个天梯了，因为是**可以直接访问的**，这是一种利好！

不得不感叹语句，Russ Cox 推动事情的能力真是杠杠的，虽然也会引来不少争议和讨论，但我们依然可以从中学习到好的部分！

大家**有没有什么也想让 Go 团队优化的呢，欢迎在评论区交流和讨论**！

================================================
FILE: content/posts/go/slice/2018-12-11-slice.md
================================================
---

title:      "深入理解 Go Slice"
date:       2018-12-11 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

![image](https://s2.ax1x.com/2020/02/27/3dXSeA.png)

## 是什么

在 Go 中，Slice（切片）是抽象在 Array（数组）之上的特殊类型。为了更好地了解 Slice，第一步需要先对 Array 进行理解。深刻了解 Slice 与 Array 之间的区别后，就能更好的对其底层一番摸索 😄

## 用法

### Array

```go
func main() {
	nums := [3]int{}
	nums[0] = 1

	n := nums[0]
	n = 2

	fmt.Printf("nums: %v\n", nums)
	fmt.Printf("n: %d\n", n)
}
```

我们可得知在 Go 中，数组类型需要指定长度和元素类型。在上述代码中，可得知 `[3]int{}` 表示 3 个整数的数组，并进行了初始化。底层数据存储为一段连续的内存空间，通过固定的索引值（下标）进行检索

![image](https://s2.ax1x.com/2020/02/27/3dXASS.png)

数组在声明后，其元素的初始值（也就是零值）为 0。并且该变量可以直接使用，不需要特殊操作

同时数组的长度是固定的，它的长度是类型的一部分，因此 `[3]int` 和 `[4]int` 在类型上是不同的，不能称为 “一个东西”

#### 输出结果

```
nums: [1 0 0]
n: 2
```

### Slice

```go
func main() {
	nums := [3]int{}
	nums[0] = 1

	dnums := nums[:]

	fmt.Printf("dnums: %v", dnums)
}
```

Slice 是对 Array 的抽象，类型为 `[]T`。在上述代码中，`dnums` 变量通过 `nums[:]` 进行赋值。需要注意的是，Slice 和 Array 不一样，它不需要指定长度。也更加的灵活，能够自动扩容

## 数据结构

![image](https://s2.ax1x.com/2020/02/27/3wmr3F.png)

```go
type slice struct {
	array unsafe.Pointer
	len   int
	cap   int
}
```

Slice 的底层数据结构共分为三部分，如下：

- array：指向所引用的数组指针（`unsafe.Pointer` 可以表示任何可寻址的值的指针）
- len：长度，当前引用切片的元素个数
- cap：容量，当前引用切片的容量（底层数组的元素总数）

在实际使用中，cap 一定是大于或等于 len 的。否则会导致 panic

### 示例

为了更好的理解，我们回顾上小节的代码便于演示，如下：

```go
func main() {
	nums := [3]int{}
	nums[0] = 1

	dnums := nums[:]

	fmt.Printf("dnums: %v", dnums)
}
```

![image](https://s2.ax1x.com/2020/02/27/3wmoge.png)

在代码中，可观察到 `dnums := nums[:]`，这段代码确定了 Slice 的 Pointer 指向数组，且 len 和 cap 都为数组的基础属性。与图示表达一致

### len、cap 不同

```go
func main() {
	nums := [3]int{}
	nums[0] = 1

	dnums := nums[0:2]

	fmt.Printf("dnums: %v, len: %d, cap: %d", dnums, len(dnums), cap(dnums))
}
```

![image](https://s2.ax1x.com/2020/02/27/3wmxC8.png)

#### 输出结果

```
dnums: [1 0], len: 2, cap: 3
```

显然，在这里指定了 `Slice[0:2]`，因此 len 为所引用元素的个数，cap 为所引用的数组元素总个数。与期待一致 😄

## 创建

Slice 的创建有两种方式，如下：

- `var []T` 或 `[]T{}`
- `func make（[] T，len，cap）[] T`

可以留意 make 函数，我们都知道 Slice 需要指向一个 Array。那 make 是怎么做的呢？

它会在调用 make 的时候，分配一个数组并返回引用该数组的 Slice

```go
func makeslice(et *_type, len, cap int) slice {
	maxElements := maxSliceCap(et.size)
	if len < 0 || uintptr(len) > maxElements {
		panic(errorString("makeslice: len out of range"))
	}

	if cap < len || uintptr(cap) > maxElements {
		panic(errorString("makeslice: cap out of range"))
	}

	p := mallocgc(et.size*uintptr(cap), et, true)
	return slice{p, len, cap}
}
```

- 根据传入的 Slice 类型，获取其类型能够申请的最大容量大小
- 判断 len 是否合规，检查是否在 0 < x < maxElements 范围内
- 判断 cap 是否合规，检查是否在 len < x < maxElements 范围内
- 申请 Slice 所需的内存空间对象。若为大型对象（大于 32 KB）则直接从堆中分配
- 返回申请成功的 Slice 内存地址和相关属性（默认返回申请到的内存起始地址）

## 扩容

当使用 Slice 时，若存储的元素不断增长（例如通过 append）。当条件满足扩容的策略时，将会触发自动扩容

那么分别是什么规则呢？让我们一起看看源码是怎么说的 😄

### zerobase

```go
func growslice(et *_type, old slice, cap int) slice {
	...
	if et.size == 0 {
		if cap < old.cap {
			panic(errorString("growslice: cap out of range"))
		}

		return slice{unsafe.Pointer(&zerobase), old.len, cap}
	}
    ...
}
```

当 Slice size 为 0 时，若将要扩容的容量比原本的容量小，则抛出异常（也就是不支持缩容操作）。否则，将重新生成一个新的 Slice 返回，其 Pointer 指向一个 0 byte 地址（不会保留老的 Array 指向）

### 扩容 - 计算策略

```go
func growslice(et *_type, old slice, cap int) slice {
    ...
    newcap := old.cap
	doublecap := newcap + newcap
	if cap > doublecap {
		newcap = cap
	} else {
		if old.len < 1024 {
			newcap = doublecap
		} else {
			for 0 < newcap && newcap < cap {
				newcap += newcap / 4
			}
			...
		}
	}
	...
}
```

- 若 Slice cap 大于 doublecap，则扩容后容量大小为 新 Slice 的容量（超了基准值，我就只给你需要的容量大小）
- 若 Slice len 小于 1024 个，在扩容时，增长因子为 1（也就是 3 个变 6 个）
- 若 Slice len 大于 1024 个，在扩容时，增长因子为 0.25（原本容量的四分之一）

注：也就是小于 1024 个时，增长 2 倍。大于 1024 个时，增长 1.25 倍

### 扩容 - 内存策略

```go
func growslice(et *_type, old slice, cap int) slice {
    ...
    var overflow bool
	var lenmem, newlenmem, capmem uintptr
	const ptrSize = unsafe.Sizeof((*byte)(nil))
	switch et.size {
	case 1:
		lenmem = uintptr(old.len)
		newlenmem = uintptr(cap)
		capmem = roundupsize(uintptr(newcap))
		overflow = uintptr(newcap) > _MaxMem
		newcap = int(capmem)
	    ...
	}

	if cap < old.cap || overflow || capmem > _MaxMem {
		panic(errorString("growslice: cap out of range"))
	}

	var p unsafe.Pointer
	if et.kind&kindNoPointers != 0 {
		p = mallocgc(capmem, nil, false)
		memmove(p, old.array, lenmem)
		memclrNoHeapPointers(add(p, newlenmem), capmem-newlenmem)
	} else {
		p = mallocgc(capmem, et, true)
		if !writeBarrier.enabled {
			memmove(p, old.array, lenmem)
		} else {
			for i := uintptr(0); i < lenmem; i += et.size {
				typedmemmove(et, add(p, i), add(old.array, i))
			}
		}
	}
	...
}
```

1、获取老 Slice 长度和计算假定扩容后的新 Slice 元素长度、容量大小以及指针地址（用于后续操作内存的一系列操作）

2、确定新 Slice 容量大于老 Sice，并且新容量内存小于指定的最大内存、没有溢出。否则抛出异常

3、若元素类型为 `kindNoPointers`，也就是**非指针**类型。则在老 Slice 后继续扩容

- 第一步：根据先前计算的 `capmem`，在老 Slice cap 后继续申请内存空间，其后用于扩容
- 第二步：将 old.array 上的 n 个 bytes（根据 lenmem）拷贝到新的内存空间上
- 第三步：新内存空间（p）加上新 Slice cap 的容量地址。最终得到完整的新 Slice cap 内存地址 `add(p, newlenmem)` （ptr）
- 第四步：从 ptr 开始重新初始化 n 个 bytes（capmem-newlenmem）

注：那么问题来了，为什么要重新初始化这块内存呢？这是因为 ptr 是未初始化的内存（例如：可重用的内存，一般用于新的内存分配），其可能包含 “垃圾”。因此在这里应当进行 “清理”。便于后面实际使用（扩容）

4、不满足 3 的情况下，重新申请并初始化一块内存给新 Slice 用于存储 Array

5、检测当前是否正在执行 GC，也就是当前是否启用 Write Barrier（写屏障），若**启用**则通过 `typedmemmove` 方法，利用指针运算**循环拷贝**。否则通过 `memmove` 方法采取**整体拷贝**的方式将 lenmem 个字节从 old.array 拷贝到 ptr，以此达到更高的效率

注：一般会在 GC 标记阶段启用 Write Barrier，并且 Write Barrier 只针对指针启用。那么在第 5 点中，你就不难理解为什么会有两种截然不同的处理方式了

#### 小结

这里需要注意的是，扩容时的内存管理的选择项，如下：

- 翻新扩展：当前元素为 `kindNoPointers`，将在老 Slice cap 的地址后继续申请空间用于扩容
- 举家搬迁：重新申请一块内存地址，整体迁移并扩容

### 两个小 “陷阱”

#### 一、同根

```go
func main() {
	nums := [3]int{}
	nums[0] = 1

	fmt.Printf("nums: %v , len: %d, cap: %d\n", nums, len(nums), cap(nums))

	dnums := nums[0:2]
	dnums[0] = 5

	fmt.Printf("nums: %v ,len: %d, cap: %d\n", nums, len(nums), cap(nums))
	fmt.Printf("dnums: %v, len: %d, cap: %d\n", dnums, len(dnums), cap(dnums))
}
```

输出结果：

```
nums: [1 0 0] , len: 3, cap: 3
nums: [5 0 0] ,len: 3, cap: 3
dnums: [5 0], len: 2, cap: 3
```

在**未扩容前**，Slice array 指向所引用的 Array。因此在 Slice 上的变更。会直接修改到原始 Array 上（两者所引用的是同一个）

![image](https://s2.ax1x.com/2020/02/27/3wnibn.png)

#### 二、时过境迁

随着 Slice 不断 append，内在的元素越来越多，终于触发了扩容。如下代码：

```go
func main() {
	nums := [3]int{}
	nums[0] = 1

	fmt.Printf("nums: %v , len: %d, cap: %d\n", nums, len(nums), cap(nums))

	dnums := nums[0:2]
	dnums = append(dnums, []int{2, 3}...)
	dnums[1] = 1

	fmt.Printf("nums: %v ,len: %d, cap: %d\n", nums, len(nums), cap(nums))
	fmt.Printf("dnums: %v, len: %d, cap: %d\n", dnums, len(dnums), cap(dnums))
}
```

输出结果：

```
nums: [1 0 0] , len: 3, cap: 3
nums: [1 0 0] ,len: 3, cap: 3
dnums: [1 1 2 3], len: 4, cap: 6
```

往 Slice append 元素时，若满足扩容策略，也就是假设插入后，原本数组的容量就超过最大值了

这时候内部就会重新申请一块内存空间，将原本的元素**拷贝**一份到新的内存空间上。此时其与原本的数组就没有任何关联关系了，**再进行修改值也不会变动到原始数组**。这是需要注意的

![image](https://s2.ax1x.com/2020/02/27/3wnAU0.png)

## 复制

### 原型

```go
func copy（dst，src [] T）int
```

copy 函数将数据从**源 Slice**复制到**目标 Slice**。它返回复制的元素数。

### 示例

```go
func main() {
	dst := []int{1, 2, 3}
	src := []int{4, 5, 6, 7, 8}
	n := copy(dst, src)

	fmt.Printf("dst: %v, n: %d", dst, n)
}
```

copy 函数支持在不同长度的 Slice 之间进行复制，若出现长度不一致，在复制时会按照最少的 Slice 元素个数进行复制

那么在源码中是如何完成复制这一个行为的呢？我们来一起看看源码的实现，如下：

```go
func slicecopy(to, fm slice, width uintptr) int {
	if fm.len == 0 || to.len == 0 {
		return 0
	}

	n := fm.len
	if to.len < n {
		n = to.len
	}

	if width == 0 {
		return n
	}

	...

	size := uintptr(n) * width
	if size == 1 {
		*(*byte)(to.array) = *(*byte)(fm.array) // known to be a byte pointer
	} else {
		memmove(to.array, fm.array, size)
	}
	return n
}
```

- 若源 Slice 或目标 Slice 存在长度为 0 的情况，则直接返回 0（因为压根不需要执行复制行为）
- 通过对比两个 Slice，获取最小的 Slice 长度。便于后续操作
- 若 Slice 只有一个元素，则直接利用指针的特性进行转换
- 若 Slice 大于一个元素，则从 `fm.array` 复制 `size` 个字节到 `to.array` 的地址处（会覆盖原有的值）

## "奇特"的初始化

在 Slice 中流传着两个传说，分别是 Empty 和 Nil Slice，接下来让我们看看它们的小区别 🤓

### Empty

```go
func main() {
	nums := []int{}
	renums := make([]int, 0)

	fmt.Printf("nums: %v, len: %d, cap: %d\n", nums, len(nums), cap(nums))
	fmt.Printf("renums: %v, len: %d, cap: %d\n", renums, len(renums), cap(renums))
}
```

输出结果：

```
nums: [], len: 0, cap: 0
renums: [], len: 0, cap: 0
```

### Nil

```go
func main() {
    var nums []int
}
```

输出结果：

```
nums: [], len: 0, cap: 0
```

### 想一想

乍一看，Empty Slice 和 Nil Slice 好像一模一样？不管是 len，还是 cap 都为 0。好像没区别？我们再看看如下代码：

```go
func main() {
	var nums []int
	renums := make([]int, 0)
	if nums == nil {
		fmt.Println("nums is nil.")
	}
	if renums == nil {
		fmt.Println("renums is nil.")
	}
}
```

你觉得输出结果是什么呢？你可能已经想到了，最终的输出结果：

```
nums is nil.
```

#### 为什么

##### Empty

![image](https://s2.ax1x.com/2020/02/27/3wncRS.png)

##### Nil

![image](https://s2.ax1x.com/2020/02/27/3wn5aq.png)

从图示中可以看出来，两者有本质上的区别。其底层数组的指向指针是不一样的，Nil Slice 指向的是 nil，Empty Slice 指向的是实际存在的空数组地址

你可以认为，Nil Slice 代指不存在的 Slice，Empty Slice 代指空集合。两者所代表的意义是完全不同的

## 总结

通过本文，可得知 Go Slice 相当灵活。不需要你手动扩容，也不需要你关注加多少减多少。对 Array 是动态引用，是 Go 类型的一个极大的补充，也因此在应用中使用的更多、更便捷

虽然有个别要注意的 “坑”，但其实是合理的。你觉得呢？😄


================================================
FILE: content/posts/go/slice/2019-01-06-why-slice-max.md
================================================
---

title:      "Go Slice 最大容量大小是怎么来的"
date:       2019-01-06 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
    - 源码分析
---

![image](https://s2.ax1x.com/2020/02/27/3wnHRU.png)

## 前言

在《深入理解 Go Slice》中，我们提到了 “根据其类型大小去获取能够申请的最大容量大小” 的处理逻辑。今天我们将更深入地去探究一下，底层到底做了什么东西，涉及什么知识点？

Go Slice 对应代码如下：

```go
func makeslice(et *_type, len, cap int) slice {
	maxElements := maxSliceCap(et.size)
	if len < 0 || uintptr(len) > maxElements {
		...
	}

	if cap < len || uintptr(cap) > maxElements {
		...
	}

	p := mallocgc(et.size*uintptr(cap), et, true)
	return slice{p, len, cap}
}
```

根据想要追寻的逻辑，定位到了 `maxSliceCap` 方法，它会根据**当前类型的大小获取到了所允许的最大容量大小**来进行阈值判断，也就是安全检查。这是浅层的了解，我们继续追下去看看还做了些什么？

## maxSliceCap

```go
func maxSliceCap(elemsize uintptr) uintptr {
	if elemsize < uintptr(len(maxElems)) {
		return maxElems[elemsize]
	}
	return maxAlloc / elemsize
}
```

## maxElems

```go
var maxElems = [...]uintptr{
	^uintptr(0),
	maxAlloc / 1, maxAlloc / 2, maxAlloc / 3, maxAlloc / 4,
	maxAlloc / 5, maxAlloc / 6, maxAlloc / 7, maxAlloc / 8,
	maxAlloc / 9, maxAlloc / 10, maxAlloc / 11, maxAlloc / 12,
	maxAlloc / 13, maxAlloc / 14, maxAlloc / 15, maxAlloc / 16,
	maxAlloc / 17, maxAlloc / 18, maxAlloc / 19, maxAlloc / 20,
	maxAlloc / 21, maxAlloc / 22, maxAlloc / 23, maxAlloc / 24,
	maxAlloc / 25, maxAlloc / 26, maxAlloc / 27, maxAlloc / 28,
	maxAlloc / 29, maxAlloc / 30, maxAlloc / 31, maxAlloc / 32,
}
```

`maxElems` 是包含一些预定义的切片最大容量值的查找表，索引是切片元素的类型大小。而值看起来 “奇奇怪怪” 不大眼熟，都是些什么呢。主要是以下三个核心点：

- ^uintptr(0)
- maxAlloc
- maxAlloc / typeSize

### ^uintptr(0)

```go
func main() {
	log.Printf("uintptr: %v\n", uintptr(0))
	log.Printf("^uintptr: %v\n", ^uintptr(0))
}
```

输出结果：

```
2019/01/05 17:51:52 uintptr: 0
2019/01/05 17:51:52 ^uintptr: 18446744073709551615
```

我们留意一下输出结果，比较神奇。取反之后为什么是 18446744073709551615 呢？

### uintptr 是什么

在分析之前，我们要知道 uintptr 的本质（真面目），也就是它的类型是什么，如下：

```go
type uintptr uintptr
```

uintptr 的类型是自定义类型，接着找它的真面目，如下：

```
#ifdef _64BIT
typedef	uint64		uintptr;
#else
typedef	uint32		uintptr;
#endif
```

通过对以上代码的分析，可得出以下结论：

- 在 32 位系统下，uintptr 为 uint32 类型，占用大小为 4 个字节
- 在 64 位系统下，uintptr 为 uint64 类型，占用大小为 8 个字节

### ^uintptr 做了什么事

^ 位运算符的作用是**按位异或**，如下：

```go
func main() {
	log.Println(^1)
	log.Println(^uint64(0))
}
```

输出结果：

```
2019/01/05 20:44:49 -2
2019/01/05 20:44:49 18446744073709551615
```

接下来我们分析一下，这两段代码都做了什么事情呢

#### ^1

二进制：0001

按位取反：1110

该数为有符号整数，最高位为符号位。低三位为表示数值。按位取反后为 1110，根据先前的说明，最高位为 1，因此表示为 -。取反后 110 对应十进制 -2

#### ^uint64(0)

二进制：0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000 0000

按位取反：1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111 1111

该数为无符号整数，该位取反后得到十进制值为：18446744073709551615

这个值是不是看起来很眼熟呢？没错，就是 `^uintptr(0)` 的值。也印证了其底层数据类型为 uint64 的事实 （本机为 64 位）。同时它又代表如下：

- math.MaxUint64
- 2 的 64 次方减 1

### maxAlloc

```go
const GoarchMips = 0
const GoarchMipsle = 0
const GoarchWasm = 0

...

_64bit = 1 << (^uintptr(0) >> 63) / 2

heapAddrBits = (_64bit*(1-sys.GoarchWasm))*48 + (1-_64bit+sys.GoarchWasm)*(32-(sys.GoarchMips+sys.GoarchMipsle))

maxAlloc = (1 << heapAddrBits) - (1-_64bit)*1
```

`maxAlloc` 是**允许用户分配的最大虚拟内存空间**。在 64 位，理论上可分配最大 `1 << heapAddrBits` 字节。在 32 位，最大可分配小于 `1 << 32` 字节

在本文，仅需了解它承载的是什么就好了。具体的在以后内存管理的文章再讲述

注：该变量在 go 10.1 为 `_MaxMem`，go 11.4 已改为 `maxAlloc`。相关的 `heapAddrBits` 计算方式也有所改变

### maxAlloc / typeSize

我们再次回顾 `maxSliceCap` 的逻辑代码，这次重点放在控制逻辑，如下：

```go
// func makeslice
maxElements := maxSliceCap(et.size)

...

// func maxSliceCap
if elemsize < uintptr(len(maxElems)) {
	return maxElems[elemsize]
}
return maxAlloc / elemsize
```

通过这段代码和 Slice 上下文逻辑，可得知在想得到该类型的最大容量大小时。会根据对应的类型大小去查找表查找索引（索引为类型大小，摆放顺序是有考虑原因的）。“迫不得已的情况下” 才会手动的计算它的值，最终计算得到的内存字节大小都为该类型大小的整数倍

查找表的设置，更像是一个优化逻辑。减少常用的计算开销 :)

## 总结

通过本文的分析，可得出 Slice 所允许申请的最大容量大小，与当前**值类型**和当前**平台位数**有直接关系

## 最后

本文与[《有点不安全却又一亮的 Go unsafe.Pointer》](https://github.com/EDDYCJY/blog/blob/master/golang/pkg/2018-12-15-%E6%9C%89%E7%82%B9%E4%B8%8D%E5%AE%89%E5%85%A8%E5%8D%B4%E5%8F%88%E4%B8%80%E4%BA%AE%E7%9A%84Go-unsafe-Pointer.md)一同属于[《深入理解 Go Slice》](https://github.com/EDDYCJY/blog/blob/master/golang/pkg/2018-12-11-%E6%B7%B1%E5%85%A5%E7%90%86%E8%A7%A3Go-Slice.md)的关联章节。如果你在阅读源码时，对这些片段有疑惑。记得想尽办法深究下去，搞懂它

短短的一句话其实蕴含着不少知识点，希望这篇文章恰恰好可以帮你解惑

注：本文 Go 代码基于版本 11.4


================================================
FILE: content/posts/go/slice-discuss.md
================================================
---
title: "Go 切片这道题，吵了一个下午！"
date: 2021-12-31T12:55:06+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前几天听到咱 Go 读者交流群里的小伙伴私聊我，表示他们在群里一直在讨论一个问题 slice 相关的问题，众说纷纭。

![来自煎鱼的聊天记录](https://files.mdnice.com/user/3610/f2cedcdf-8f6e-42f9-9009-6f1ee0f74f91.png)

今天和各位小伙伴们一起来研究一下，避免后续又踩一遍坑，共同进步！

## 问题代码

引起群内大范围讨论的代码如下：

```golang
func main() {
	sl := make([]int, 0, 10)
	var appenFunc = func(s []int) {
		s = append(s, 10, 20, 30)
		fmt.Println(s)
	}
	fmt.Println(sl)
	appenFunc(sl)
	fmt.Println(sl)
	fmt.Println(sl[:10])
}
```

你认为程序的输出结果是什么？

是如下的答案：

```
[]
[10 20 30]
[]
[]
```

对吗？

看上去很有道理，但错了。正确的结果是：

```
[]
[10 20 30]
[]
[10 20 30 0 0 0 0 0 0 0]
```

这下可把大家整懵了，为什么输出 `sl` 和 `sl[:10]` 的结果差别这么大，这与预期的输出结果不一致。

群内小伙伴的问题更明确了，疑惑点是：

```golang
	fmt.Println(sl)     
	fmt.Println(sl[:10]) 
```

上述代码中，**为什么第一个 `sl` 打印结果是空的，第二个 `sl` 给索引位置就能打印出来**？

也有小伙伴不断在尝试 `sl[:10]` 以外的输出，有没有因为一些边界值改变而导致不行。

例如：

```golang
fmt.Println(sl[:])
```

你认为这个对应的输出结果是什么？

是如下的答案：

```
[10 20 30 0 0 0 0 0 0 0]
```

对吗？

看上去很有道理，但错了。正确的结果是：

```
[]
```

是没有任何元素输出，这下大家更懵了。为什么 `sl[:]` 的输出结果为空？

再看看变量 `sl` 的长度和容量：

```
fmt.Println(len(sl), cap(sl))
```

输出结果：

```
0 10
```

长度竟然是 0 ...迷了？

## 挖掘原因

### 三个问题
在研究了问题代码的表象后，我们要进一步的挖掘问题的原因。

请思考如下三个问题：
1. 为什么打印 `sl[:10]` 时，结果包含了 10 个元素，还包含了函数闭包中插入的 10, 20, 30，之间有什么关系？
2. 为什么打印 `sl` 变量时，结果为空？
3. 为什么打印 `sl[:]` 时，结果为空。但打印 `sl[:10]` 就正常输出？

### 了解底层

要分析起源，我们就必须要再提到 slice（切片）的底层实现，slice 底层存储的数据结构指向了一个 array（数组）。

如下：

![slice 和 array 的友谊小船](https://files.mdnice.com/user/3610/6a025aba-38f0-4ac5-92bb-515d05adeb68.png)

对应的 Slice 在运行时的表现是 SliceHeader 结构体，定义如下：

```golang
type SliceHeader struct {
 Data uintptr
 Len  int
 Cap  int
}
```
- Data：指向具体的底层数组。
- Len：代表切片的长度。
- Cap：代表切片的容量。

核心要记住的是：slice 真正存储数据的地方，是一个数组。slice 的结构中**存储的是指向所引用的数组指针地址**。

### 分析原因

在了解 slice 的底层后，我们需要来分析问题的起源，也就是那段 Go 程序。

我们关注到 `appenFunc` 变量，他其实是一个函数，并且结果中我们所看到的 10, 20, 30，也只有这里有插入的动作。因此这是需要分析的。

如下：

```golang
func main() {
	sl := make([]int, 0, 10)
	var appenFunc = func(s []int) {
		s = append(s, 10, 20, 30)
	}
	appenFunc(sl)
	fmt.Println(sl)
	fmt.Println(sl[:10])
}
```

但为什么在 `appenFunc` 函数中所插入的 10, 20, 30 元素，就跑到外面的切片 `sl` 中去了呢？

这其实结合 slice 的底层设计和函数传递就明白了，**在 Go 语言中，只有值传递**：

![](https://files.mdnice.com/user/3610/3d2999da-e405-4a42-ba37-858487052c3b.png)

具体可详见我之前写的《[又吵起来了，Go 是传值还是传引用？](https://mp.weixin.qq.com/s/qsxvfiyZfRCtgTymO9LBZQ)》，有明确分析和说明。

实质上在调用 `appenFunc(sl)` 函数时，**实际上修改了底层所指向的数组**，自然也就会发生变化，也就不难理解为什么 10, 20, 30 元素会出现了。

那为什么 `sl` 变量的长度是 0，甚至有人猜测是不是扩容了，这其实和上面的问题还是一样，因为是值传递，自然也就不会发生变化。

要记住一个关键点：**如果传过去的值是指向内存空间的地址，是可以对这块内存空间做修改的**。反之，你也改不了。

至此，也就解决了我们的第一个大问题。

### 切片小优化

还剩下两个大问题，这似乎用上面的结论没法完整解释。虽说程序是诱因，但这块最直接的影响是和切片访问的小优化有关。

常用的访问切片我们会用：

```
s[low : high]
```

注意这里是：low、high。可没有用 len、cap 这种定性的词语，也就代表着这里取的值是可变的。

当是切片（slice）时，表达式 `s[low : high]` 中的 high，**最大的取值范围对应着切片的容量（cap），不是单纯的长度（len）**。因此调用 `fmt.Println(sl[:10])` 时可以输出容量范围内的值，不会出现越界。

相对的 `fmt.Println(sl)` 因为该切片 len 值为 0，没有指定最大索引值，high 则取 len 值，导致输出结果为空。

至此，第二和第三个大问题就解决了。

注：访问元素的定位在 Go 编译期就确定的了，相关逻辑可以在 compile 相关的代码中看到。

## 总结

在今天这篇文章中，我们结合了 Go 语言中切片的基本底层原理、值传递、边界值取值等进行了多轮探讨。

我们要牢记：**如果传过去的值是指向内存空间的地址，是可以对这块内存空间做修改的**。这在多种应用场景下都是适用的。

**所谓的最大取值范围**，除非官方给你写定 len 或 cap，否则不要过于主观的认为，因为他**会根据访问的数据类型和访问定位等改变**。

注：欢迎大家一起多多讨论，加我微信号：cJY0728，备注：加群。我拉你进读者交流群，和大家一起捣鼓技术，突破自己。

## 参考
- 来自读者 1v1 私聊
- 来自 Go 读者群

================================================
FILE: content/posts/go/slice-leak.md
================================================
---
title: "Go 切片导致内存泄露，被坑两次了！"
date: 2021-12-31T12:55:09+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间在我的 Go 读者群里，有小伙伴们在纠结切片（slice）的问题，我写了这篇《[Go 切片这道题，吵了一个下午！](https://mp.weixin.qq.com/s/kEQI74ge6VhvNEr1d3JW-Q)》，引起了一拨各种讨论，还是比较欣慰的。

这不，有小伙伴给我提出了新的题材：

![来自读者微信提问](https://files.mdnice.com/user/3610/a97e5e6d-b58d-44f2-b858-b9ca12780180.png)

提出的是 Go 中很容易踩坑的切片内存泄露问题。作为宠粉的煎鱼肯定不会放过，争取让大家都避开这个 “坑”。

今天这篇文章，就由煎鱼带大家来了解这个问题：Go 切片可能可以怎么泄露法？

## 切片泄露的可能

在业务代码的编写上，我们经常会接受来自外部的接口数据，再把他插入到对应的数据结构中去，再进行下一步的业务聚合、裁剪、封装、处理。

像在 PHP 语言，常常会放到数组（array）中。在 Go 语言，会放到切片（slice）中。因此在 Go 的切片处理逻辑中，常常会涉及到如下类似的动作。

示例代码如下：

```golang
var a []int

func f(b []int) []int {
	a = b[:2]
	return a
}

func main() {
    ...
}
```

仔细想想，**这段程序有没有问题**，是否存在内存泄露的风险？

答案是：有的。有明确的切片内存泄露的可能性和风险。

## 切片底层结构

可能有些小伙伴会疑惑，怎么就有问题了，是哪里有问题？

这里就得复习一下切片的底层基本数据结构了，切片在运行时的表现是 SliceHeader 结构体，定义如下：

```golang
type SliceHeader struct {
 Data uintptr
 Len  int
 Cap  int
}
```
- Data：指向具体的底层数组。
- Len：代表切片的长度。
- Cap：代表切片的容量。

要点是：切片真正存储数据的地方，是一个数组。切片的 Data 属性中**存储的是指向所引用的数组指针地址**。

## 背后的原因

在上述案例中，我们有一个包全局变量 a，共有 2 个切片 a 和 b，截取了 b 的一部分赋值给了 a，两者存在着关联。

从程序的直面来看，截取了 b 的一部分赋值给了 a，结构似乎是如下图：

![](https://files.mdnice.com/user/3610/856aff0a-14bb-4dca-9324-4b852f25dd12.png)

但我们进一步打开程序底层来看，他应该是如下图所示：

![](https://files.mdnice.com/user/3610/c79008dd-771d-475b-8c41-6b654216feff.png)

切片 a 和 b 都共享着同一个底层数组（共享内存块），sliceB 包含全部所引用的字符。sliceA 只包含了 [:2]，也就是 0 和 1 两个索引位的字符。

那他们泄露在哪里了？

## 泄露的点

泄露的点，就在于虽然切片 b 已经在函数内结束了他的使命了，不再使用了。但切片 a 还在使用，切片 a 和 切片 b 引用的是同一块底层数组（共享内存块）。

关键点：**切片 a 引用了底层数组中的一段**。

![](https://files.mdnice.com/user/3610/0a4353e0-e793-41b5-a2dc-a6a25a39a519.png)

虽然切片 a 只有底层数组中 0 和 1 两个索引位正在被使用，其余未使用的底层数组空间毫无作用。但由于正在被引用，他们也不会被 GC，因此造成了泄露。

## 解决办法

解决的办法，就是利用切片的特性。当切片的容量空间不足时，会**重新申请一个新的底层数组来存储，让两者彻底分手**。

示例代码如下：

```golang
var a []int
var c []int    // 第三者

func f(b []int) []int {
	a = b[:2]
  
  // 新的切片 append 导致切片扩容
	c = append(c, b[:2]...)
	fmt.Printf("a: %p\nc: %p\nb: %p\n", &a[0], &c[0], &b[0])
  
	return a
}
```

输出结果：

```
a: 0xc000102060
c: 0xc000124010
b: 0xc000102060
```

这段程序，新增了一个变量 c，他容量为 0。此时将期望的数据，追加过去。自然而然他就会遇到容量空间不足的情况，也就能实现申请新底层数据。

我们再将原本的切片置为 nil，就能成功实现两者分手的目标了。

## 总结

在今天这篇文章中，我们介绍了 Go 切片的一种常见的内存泄露方式。虽然我们在日常使用的时候可能没关注到。

主要原因还是由于切片的大多数使用场景，体量都比较小。又或是不知不觉就自己扩容了，就变成暂时性泄露了。

这依然是存在风险的，在编写 Go 代码时需要谨慎。毕竟这可是 **Go 语言官方自己都踩过坑的 “坑”**。

## 参考
- [An interesting way to leak memory with Go slices](https://utcc.utoronto.ca/~cks/space/blog/programming/GoSlicesMemoryLeak)
- [internal/poll: avoid memory leak in Writev](https://github.com/golang/go/pull/32138/files)
- [slice 类型内存泄露的逻辑](https://xargin.com/logic-of-slice-memory-leak/)
- [golang slice内存泄露回收](https://zhuanlan.zhihu.com/p/149381458)

================================================
FILE: content/posts/go/slice-string-header.md
================================================
---
title: "Go SliceHeader 和 StringHeader，你知道吗？"
date: 2021-12-31T12:54:53+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

在 Go 语言中总是有一些看上去奇奇怪怪的东西，咋一眼一看感觉很熟悉，但又不理解其在 Go 代码中的实际意义，面试官却爱问...

今天要给大家介绍的是 SliceHeader 和 StringHeader 结构体，了解清楚他到底是什么，又有什么用，并且会在最后给大家介绍 0 拷贝转换的内容。

一起愉快地开始吸鱼之路。

SliceHeader
-----------

SliceHeader 如其名，Slice + Header，看上去很直观，实际上是 Go Slice（切片）的运行时表现。

SliceHeader 的定义如下：

```
type SliceHeader struct {
 Data uintptr
 Len  int
 Cap  int
}
```

*   Data：指向具体的底层数组。
    
*   Len：代表切片的长度。
    
*   Cap：代表切片的容量。
    

既然知道了切片的运行时表现，那是不是就意味着我们可以自己造一个？

在日常程序中，可以利用标准库 `reflect` 提供的 `SliceHeader` 结构体造一个：

```
func main() {
  // 初始化底层数组
 s := [4]string{"脑子", "进", "煎鱼", "了"}
 s1 := s[0:1]
 s2 := s[:]

  // 构造 SliceHeader
 sh1 := (*reflect.SliceHeader)(unsafe.Pointer(&s1))
 sh2 := (*reflect.SliceHeader)(unsafe.Pointer(&s2))
 fmt.Println(sh1.Len, sh1.Cap, sh1.Data)
 fmt.Println(sh2.Len, sh2.Cap, sh2.Data)
}
```

你认为输出结果是什么，这两个新切片会指向同一个底层数组的内存地址吗？

输出结果：

```
1 4 824634330936
4 4 824634330936
```

两个切片的 Data 属性所指向的底层数组是一致的，Len 属性的值不一样，sh1 和 sh2 分别是两个切片。

### 疑问

为什么两个新切片所指向的 Data 是同一个地址的呢？

这其实是 Go 语言本身为了减少内存占用，提高整体的性能才这么设计的。

将切片复制到任意函数的时候，对底层数组大小都不会影响。复制时只会复制切片本身（值传递），不会涉及底层数组。

也就是在函数间传递切片，其只拷贝 24 个字节（指针字段 8 个字节，长度和容量分别需要 8 个字节），效率很高。

### 坑

这种设计也引出了新的问题，在平时通过 `s[i:j]` 所生成的新切片，两个切片底层指向的是同一个底层数组。

假设**在没有超过容量（cap）的情况下，对第二个切片操作会影响第一个切片**。

这是很多 Go 开发常会碰到的一个大 “坑”，不清楚的排查了很久的都不得而终。

StringHeader
------------

除了 SliceHeader 外，Go 语言中还有一个典型代表，那就是字符串（string）的运行时表现。

StringHeader 的定义如下：

```
type StringHeader struct {
   Data uintptr
   Len  int
}
```

*   Data：存放指针，其指向具体的存储数据的内存区域。
    
*   Len：字符串的长度。
    

可得知 “Hello” 字符串的底层数据如下：

```
var data = [...]byte{
    'h', 'e', 'l', 'l', 'o',
}
```

底层的存储示意图如下：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/30ace7491055413eadaf97c05de85b9c~tplv-k3u1fbpfcp-zoom-1.image)

图来自网络

真实演示例子如下：

```
func main() {
 s := "脑子进煎鱼了"
 s1 := "脑子进煎鱼了"
 s2 := "脑子进煎鱼了"[7:]

 fmt.Printf("%d \n", (*reflect.StringHeader)(unsafe.Pointer(&s)).Data)
 fmt.Printf("%d \n", (*reflect.StringHeader)(unsafe.Pointer(&s1)).Data)
 fmt.Printf("%d \n", (*reflect.StringHeader)(unsafe.Pointer(&s2)).Data)
}
```

你认为输出结果是什么，变量 s 和 s1、s2 会指向同一个底层内存空间吗？

输出结果：

```
17608227 
17608227 
17608234 
```

从输出结果来看，变量 s 和 s1 指向同一个内存地址。变量 s2 虽稍有偏差，但本质上也是指向同一块。

因为其是字符串的切片操作，是从第 7 位索引开始，因此正好的 17608234-17608227 = 7。也就是三个变量都是指向同一块内存空间，这是为什么呢？

这是因为在 Go 语言中，**字符串都是只读的，为了节省内存，相同字面量的字符串通常对应于同一字符串常量，因此指向同一个底层数组**。

0 拷贝转换
------

为什么会有人关注到 SliceHeader、StringHeader 这类运行时细节呢，一大部分原因是业内会有开发者，**希望利用其实现零拷贝的 string 到 bytes 的转换**。

常见转换代码如下：

```
func string2bytes(s string) []byte {
 stringHeader := (*reflect.StringHeader)(unsafe.Pointer(&s))

 bh := reflect.SliceHeader{
  Data: stringHeader.Data,
  Len:  stringHeader.Len,
  Cap:  stringHeader.Len,
 }

 return *(*[]byte)(unsafe.Pointer(&bh))
}
```

但这其实是错误的，官方明确表示：

>  the Data field is not sufficient to guarantee the data it references will not be garbage collected, so programs must keep a separate, correctly typed pointer to the underlying data.

SliceHeader、StringHeader 的 Data 字段是一个 `uintptr` 类型。由于 Go 语言只有值传递。

因此在上述代码中会出现将 `Data` 作为值拷贝的情况，这就会导致**无法保证它所引用的数据不会被垃圾回收（GC）**。

应该使用如下转换方式：

```
func main() {
 s := "脑子进煎鱼了"
 v := string2bytes1(s)
 fmt.Println(v)
}

func string2bytes1(s string) []byte {
 stringHeader := (*reflect.StringHeader)(unsafe.Pointer(&s))

 var b []byte
 pbytes := (*reflect.SliceHeader)(unsafe.Pointer(&b))
 pbytes.Data = stringHeader.Data
 pbytes.Len = stringHeader.Len
 pbytes.Cap = stringHeader.Len

 return b
}
```

在程序必须保留一个单独的、正确类型的指向底层数据的指针。

在性能方面，若只是期望单纯的转换，对容量（cap）等字段值不敏感，也可以使用以下方式：

```
func string2bytes2(s string) []byte {
 return *(*[]byte)(unsafe.Pointer(&s))
}
```

性能对比：

```
string2bytes1-1000-4   3.746 ns/op  0 allocs/op
string2bytes1-1000-4   3.713 ns/op  0 allocs/op
string2bytes1-1000-4   3.969 ns/op  0 allocs/op

string2bytes2-1000-4   2.445 ns/op  0 allocs/op
string2bytes2-1000-4   2.451 ns/op  0 allocs/op
string2bytes2-1000-4   2.455 ns/op  0 allocs/op
```

会相当标准的转换性能会稍快一些，这种强转也会导致一个小问题。

代码如下：

```
func main() {
 s := "脑子进煎鱼了"
 v := string2bytes2(s)
 println(len(v), cap(v))
}
func string2bytes2(s string) []byte {
 return *(*[]byte)(unsafe.Pointer(&s))
}
```

输出结果：

```
18 824633927632

```

这种强转其会导致 byte 的切片容量非常大，需要特别注意。一般还是推荐使用标准的 SliceHeader、StringHeader 方式就好了，也便于后来的维护者理解。

总结
--

在这篇文章中，我们介绍了字符串（string）和切片（slice）的两个运行时表现，分别是 StringHeader 和 SliceHeader。

同时了解到其运行时表现后，我们还针对其两者的地址指向，常见坑进行了说明。

最后我们进一步深入，面向 0 拷贝转换的场景进行了介绍和性能分析。

你平时有没有遇到过这块的疑惑或问题呢，欢迎大家一起讨论！

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，学习 Go 语言可以看 [Go 学习地图和路线](https://github.com/eddycjy/go-developer-roadmap)，欢迎 Star 催更。


参考
--

*   Go语言slice的本质-SliceHeader
    
*   数组、字符串和切片
    
*   零拷贝实现string 和bytes的转换疑问


================================================
FILE: content/posts/go/stop-goroutine.md
================================================
---
title: "回答我，停止 Goroutine 有几种方法？"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

协程（goroutine）作为 Go 语言的扛把子，经常在各种 Go 工程项目中频繁露面，甚至有人会为了用 goroutine 而强行用他。

在 Go 工程师的面试中，也绕不开他，会有人问 ”如何停止一个 goroutine？”，一下子就把话题范围扩大了，这是一个涉及多个知识点的话题，能进一步深入问。

为此，今天煎鱼就带大家了解一下停止 goroutine 的方法！

## goroutine 案例

在日常的工作中，我们常会有这样的 Go 代码，go 关键字一把搜起一个 goroutine：

```golang
func main() { 
	ch := make(chan string, 6)
	go func() {
		for {
			ch <- "脑子进煎鱼了"
		}
	}()
}
```

初入 goroutine 大门的开发者可能就完事了，但跑一段时间后，他就可能会遇到一些问题，苦苦排查...

像是：当 goroutine 内的任务，运行的太久，又或是卡死了...就会一直阻塞在系统中，变成 goroutine 泄露，或是间接造成资源暴涨，会带来许多的问题。

如何在停止 goroutine，就成了一门必修技能了，不懂就没法用好 goroutine。

## 关闭 channel

第一种方法，就是借助 channel 的 close 机制来完成对 goroutine 的精确控制。

代码如下：

```golang
func main() {
	ch := make(chan string, 6)
	go func() {
		for {
			v, ok := <-ch
			if !ok {
				fmt.Println("结束")
				return
			}
			fmt.Println(v)
		}
	}()

	ch <- "煎鱼还没进锅里..."
	ch <- "煎鱼进脑子里了！"
	close(ch)
	time.Sleep(time.Second)
}
```

在 Go 语言的 channel 中，channel 接受数据有两种方法：

```golang
msg := <-ch
msg, ok := <-ch
```

这两种方式对应着不同的 runtime 方法，我们可以利用其第二个参数进行判别，当关闭 channel 时，就根据其返回结果跳出。

另外我们也可以利用 `for range` 的特性：

```golang
	go func() {
		for {
			for v := range ch {
				fmt.Println(v)
			}
		}
	}()
```

其会一直循环遍历通道 `ch`，直到其关闭为止，是颇为常见的一种用法。

## 定期轮询 channel

第二种方法，是更为精细的方法，其结合了第一种方法和类似信号量的处理方式。

代码如下：

```golang
func main() {
	ch := make(chan string, 6)
	done := make(chan struct{})
	go func() {
		for {
			select {
			case ch <- "脑子进煎鱼了":
			case <-done:
				close(ch)
				return
			}
			time.Sleep(100 * time.Millisecond)
		}
	}()

	go func() {
		time.Sleep(3 * time.Second)
		done <- struct{}{}
	}()

	for i := range ch {
		fmt.Println("接收到的值: ", i)
	}

	fmt.Println("结束")
}
```

在上述代码中，我们声明了变量 `done`，其类型为 channel，用于作为信号量处理 goroutine 的关闭。

而 goroutine 的关闭是不知道什么时候发生的，因此在 Go 语言中会利用 `for-loop` 结合 `select` 关键字进行监听，再进行完毕相关的业务处理后，再调用 `close` 方法正式关闭 channel。

若程序逻辑比较简单结构化，也可以不调用 `close` 方法，因为 goroutine 会自然结束，也就不需要手动关闭了。

## 使用 context

第三种方法，可以借助 Go 语言的上下文（context）来做 goroutine 的控制和关闭。

代码如下：

```golang
func main() {
	ch := make(chan struct{})
	ctx, cancel := context.WithCancel(context.Background())

	go func(ctx context.Context) {
		for {
			select {
			case <-ctx.Done():
				ch <- struct{}{}
				return
			default:
				fmt.Println("煎鱼还没到锅里...")
			}

			time.Sleep(500 * time.Millisecond)
		}
	}(ctx)

	go func() {
		time.Sleep(3 * time.Second)
		cancel()
	}()

	<-ch
	fmt.Println("结束")
}
```

在 context 中，我们可以借助 `ctx.Done` 获取一个只读的 channel，类型为结构体。可用于识别当前 channel 是否已经被关闭，其原因可能是到期，也可能是被取消了。

因此 context 对于跨 goroutine 控制有自己的灵活之处，可以调用 `context.WithTimeout` 来根据时间控制，也可以自己主动地调用 `cancel` 方法来手动关闭。

## 干掉另外一个 goroutine

在了解了停止 goroutine 的 3 种经典方法后，又有小伙伴提出了新的想法。就是 “**我想在 goroutineA 里去停止 goroutineB，有办法吗？**”

答案是不能，因为在 Go 语言中，goroutine 只能自己主动退出，一般通过 channel 来控制，不能被外界的其他 goroutine 关闭或干掉，也没有 goroutine 句柄的显式概念。

![go/issues/32610](https://files.mdnice.com/user/3610/6c9da671-cc06-4eef-8911-915fd470375f.png)

在 Go issues 中也有人提过类似问题，Dave Cheney 给出了一些思考：

- 如果一个 goroutine 被强行停止了，它所拥有的资源会发生什么？堆栈被解开了吗？defer 是否被执行？
  - 如果执行 defer，该 goroutine 可能可以继续无限期地生存下去。
  - 如果不执行 defer，该 goroutine 原本的应用程序系统设计逻辑将会被破坏，这肯定不合理。
- 如果允许强制停止 goroutine，是要释放所有东西，还是直接把它从调度器中踢出去，你想通过此解决什么问题？

这都是值得深思的，另外一旦放开这种限制。作为程序员，你维护代码。很有可能就不知道 goroutine 的句柄被传到了哪里，又是在何时何地被人莫名其妙关闭，非常糟糕...

## 总结

在今天这篇文章中，我们介绍了在 Go 语言中停止 goroutine 的三大经典方法（channel、context，channel+context）和其背后的使用原理。

同时针对 goroutine 不可以跨 goroutine 强制停止的原因进行了分析。其实 goroutine 的设计就是这样的，包括像 goroutine+panic+recover 的设计也是遵循这个原理，因此也有的 Go 开发者总是会误以为跨 goroutine 能有 recover 接住...

记住，在 Go 语言中**每一个 goroutine 都需要自己承担自己的任何责任**，这是基本原则。

（你已经是一个成熟的 goroutine 了...）

## 参考
- [How to stop a goroutine](https://stackoverflow.com/questions/6807590/how-to-stop-a-goroutine)

================================================
FILE: content/posts/go/struct-pointer.md
================================================
---
title: "你知道 Go 结构体和结构体指针调用有什么区别吗？"
date: 2021-06-06T12:21:30+08:00
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

前几天在分享《Go 结构体是否可以比较，为什么？》时，有小伙伴提出了新的问题：

![来自文章评论区](https://image.eddycjy.com/a4d34c5312339b9909e482c18f0cdf4a.png)

虽然大家提问题的速度已经超出了本鱼写文章的速度...不过作为宠粉狂鱼，在此刻清明假期时还是写下了这篇文章。

我在网上冲浪时搜索了相关问题，发现 6 年前就有 Go 开发者有一模一样的疑问，真是困扰了一代又一代的小伙伴。

![来自 stackoverflow.com](https://image.eddycjy.com/dbe910917c86e103648e314f79896a81.png)


本期的男主角是《**Go 结构体和结构体指针调用有什么区别**》，希望对大家有所帮助，带来一些思考。

**请在此处默念自己心目中的答案**，再和煎鱼一同研讨一波 Go 的技术哲学。

## 结构体是什么

在 Go 语言中有个基本类型，开发者们称之为结构体（struct）。是 Go 语言中非常常用的，基本定义：

```golang
type struct_variable_type struct {
    member definition
    member definition
    ...
    member definition
}
```

简单示例：

```golang
package main

import "fmt"

type Vertex struct {
    Name1 string
    Name2 string
}

func main() {
    v := Vertex{"脑子进了", "煎鱼"}
    v.Name2 = "蒸鱼"
    fmt.Println(v.Name2)
}
```

输出结果：

```
蒸鱼
```

这部分属于基础知识，因此不再过多解释。如果看不懂，建议重学 Go 语言语法基础。

## 结构体和指针调用

讲解前置概要后，直接进入本文主题。如下例子：

```golang
type MyStruct struct {
    Name string
}

func (s MyStruct) SetName1(name string) {
    s.Name = name
}

func (s *MyStruct) SetName2(name string) {
    s.Name = name
}
```

该程序声明了一个 `User` 结构体，其包含两个结构体方法，分别是 `SetName1` 和 `SetName2` 方法，两者之间的差异就是**引用的方式不同**。

进一步延伸，这两者有什么区别，什么情况下用哪种，有没有什么注意事项？

注：很巧，我有一个朋友，当年刚上手 Go 语言时，就纠结过这个问题。

## 两者区别

从许多小伙伴的反馈来看，这两个例子之间的区别可能会让人感到困惑，经常会有人纠结要不要使用 “指针”，又担心 GC 什么的。

实际上情况没那么复杂，看看下面的例子：

```golang
func (s MyStruct) SetName1(name string) 
func (s *MyStruct) SetName2(name string)
```
当在一个类型上定义一个方法时，接收器（在上面的例子中是 s）的行为就像它是方法的一个参数一样。其相当于：

```golang
 func SetName1(s MyStruct, name string){
    u.Name = name
 }

 func SetName2(s *MyStruct,name string){
    u.Name = name
 }
```

因此结构体方法是要将接收器定义成值，还是指针。这本质上与函数参数应该是值还是指针是同一个问题。

## 如何选择

整体有以下几个考虑因素，按重要程度顺序排列：

1. 在使用上的考虑：方法是否需要修改接收器？如果需要，接收器必须是一个指针。

2. 在效率上的考虑：如果接收器很大，比如：一个大的结构体，使用指针接收器会好很多。

3. 在一致性上的考虑：如果类型的某些方法必须有指针接收器，那么其余的方法也应该有指针接收器，所以无论类型如何使用，方法集都是一致的。

回到上面的例子中，从功能使用角度来看：
- 如果 `SetName2` 方法修改了 s 的字段，调用者是可以看到这些字段值变更的，因为其是指针引用，本质上是同一份。
- 相对 `SetName1` 方法来讲，该方法是用调用者参数的副本来调用的，本质上是值传递，它所做的任何字段变更对调用者来说是看不见的。

另外对于基本类型、切片和小结构等类型，值接收器是非常廉价的。

因此除非方法的语义需要指针，那么值接收器是最高效和清晰的。在 GC 方面，也不需要过度关注。出现时再解决就好了。

## 总结

在本文中，我们针对 Go 结构体和结构体指针调用有什么区别，这个问题进行了深入浅出的分析和说明。

而在本文中所介绍的部分内容，来自于官方 FAQ 的 “Should I define methods on values or pointers?”，可以认为是官方给出的基本解答了（问的人是真的多）。

谁疑惑这个问题，转发这篇文章，吸就完了。

================================================
FILE: content/posts/go/switch-type.md
================================================
---
title: "Go 泛型玩出花，详解新提案 switch type！"
date: 2021-12-31T12:55:23+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前面写过好几篇 Go 泛型的语法、案例介绍，新的一手 Go 消息。实际上，随着一些提案被接受，新的提案也逐渐冒出。

这不，我发现有了泛型后，大家可以更进一步玩出花来了。看到了一个 ”新“ 提案《[proposal: spec: generics: type switch on parametric types](https://github.com/golang/go/issues/45380 "proposal: spec: generics: type switch on parametric types")》，讲的就是增加泛型后的参数类型上的类型开关诉求。

跟着煎鱼一起掌握新的 Go 知识吧！

## 新提案

新的提案内容是希望增加一个新的变种语句，允许在 switch 语句中使用泛型时，能够进一步便捷的约束其类型参数。

例如：

```go
switch type T {
case A1:
case A2, A3:
   ...
}
```

也就是 switch-type 语句的 **T 类型可以是一个泛型的类型参**，case 所对应的的类型可以是任何类型，包括泛型的约束类型。

假设类型 T 的类型有可能是以下：

```go
interface{
    C
    A
}
```

可以借助泛型的近似元素来约束：

```go
    interface{
        C
        A1 | A2 | ... | An
    }
```

甚至还可以在 case 上有新的写法：

```go
case interface {~T}:
```

在支持泛型后，**switch 在 type 和 case 上会存在很多种可能性**，需要进行具体的特性支持，这个提案就是为此出现。

## 实际案例

### 案例一：多类型元素

```go
type Stringish interface {
	string | fmt.Stringer
}

func Concat[S Stringish](x []S "S Stringish") string {
    switch type S {
    case string:
        ...
    case fmt.Stringer:
        ...
    }
 }
```

类型 S 能够支持 string 和 fmt.Stringer 类型，case 配套对应实现。

### 案例二：近似元素

```go
type Constraint interface {
    ~int | ~int8 | ~string
}

func ThisSyntax[T Constraint]( "T Constraint") {
    switch type T {
    case ~int | ~int8:
        ...
    case ~string:
        ...
    }
}

func IsClearerThanThisSyntax[T Constraint]( "T Constraint") {
    switch type T {
    case interface{~int | ~int8 }:
        ...
    case interface{ ~string }:
        ...
    }
}
```

类型 T 可能有很多类型，程序中用到了近似元素，也就是基础类型是 int、int8、string，这些类型中的任何一种都能够满足这个约束。

为此，switch-type 支持了，case 也要配套支持该特性。

## 争议点

看到这里可能大家也想到了，这个味道很似曾相识，好像某个语法能够支持。因此，这个提案下最有争议的，就是与原有的类型断言的重复。

原有的类型断言如下：

```go
switch T.(type) {
case string:
   ...
default:
   ...
}
```

新的类型判别如下：

```go
switch type T {
case A1:
case A2, A3:
   ...
}
```

这么咋一看，其实类型断言的完全可以取代新的，那岂不是重复建设，造轮子了？

其实是没有完全取代的。差异点如下：

```go
type ApproxString interface { ~string }

func F[T ApproxString](v T "T ApproxString") {
    switch (interface{})(v).(type) {
    case string:
        fmt.Println(v)
    default:
        panic("脑子没进煎鱼")
    }
}

type MyString string

func main() {
    F(MyString("脑子进煎鱼了"))
}
```

看出来差别在哪了吗，答案是什么？


答案是：会抛出恐慌（panic）。

你可能纠结了，问题出在哪里？这传入的 ”脑子进煎鱼了“ 的类型是 `MyString`，他的基础类型是 `string` 类型，也满足 `ApproxString` 类型的近似类型 `~string` 的要求，怎么就不行了...

根本原因是因为他的类型是 interface，而非 string 类型。所以走到了 defalut 分支的恐慌。


## 总结

今天给大家介绍了 Go 泛型的最新消息，在上一个提案被合并后，该提案也有一些新的动静。不过 Go 官方表态，会等熟练掌握泛型实践后，再继续推动该提案。

我相信，原有的 `switch.(type)` 和 `switch type` 很大概率在 Go 底层会变成同一个逻辑块处理，再逐渐过渡。

这个提案的目的还是**为了解决若干引入泛型后，所带入的 BUG/需求**，正正是需要新的语法结构来解决的。

**你对此有什么看法呢**，欢迎在评论区留言和交流：）

================================================
FILE: content/posts/go/sync-map.md
================================================
---
title: "Go 并发读写 sync.map 的强大之处"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

在之前的 《[为什么 Go map 和 slice 是非线程安全的？](http://mp.weixin.qq.com/s?__biz=MzUxMDI4MDc1NA==&mid=2247489045&idx=1&sn=197bda427246e16907c7b471a5dc0572&chksm=f9040348ce738a5ebf541954a4de29ce746238ab7f6e5a2af8a1765c5383ad4208f43b2bac4f&scene=21#wechat_redirect)》 文章中，我们讨论了 Go 语言的 map 和 slice 非线程安全的问题，基于此引申出了 map 的两种目前在业界使用的最多的并发支持的模式。

分别是：

*   原生 map + 互斥锁或读写锁 mutex。
    
*   标准库 sync.Map（Go1.9及以后）。
    

有了选择，总是有选择困难症的，这**两种到底怎么选，谁的性能更加的好**？我有一个朋友说 标准库 sync.Map 性能菜的很，不要用。我到底听谁的...

今天煎鱼就带你揭秘 Go sync.map，我们先会了解清楚什么场景下，Go map 的多种类型怎么用，谁的性能最好！

接着根据各 map 性能分析的结果，针对性的对 sync.map 进行源码解剖，了解 WHY。

一起愉快地开始吸鱼之路。

sync.Map 优势
-----------

在 Go 官方文档中明确指出 Map 类型的一些建议：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/6500ee41a08a415ca681fa427f5032b3~tplv-k3u1fbpfcp-zoom-1.image)

*   多个 goroutine 的并发使用是安全的，不需要额外的锁定或协调控制。
    
*   大多数代码应该使用原生的 map，而不是单独的锁定或协调控制，以获得更好的类型安全性和维护性。
    

同时 Map 类型，还针对以下场景进行了性能优化：

*   当一个给定的键的条目只被写入一次但被多次读取时。例如在仅会增长的缓存中，就会有这种业务场景。
    
*   当多个 goroutines 读取、写入和覆盖不相干的键集合的条目时。
    

这两种情况与 Go map 搭配单独的 Mutex 或 RWMutex 相比较，使用 Map 类型可以大大减少锁的争夺。

性能测试
----

听官方文档介绍了一堆好处后，他并没有讲到缺点，所说的性能优化后的优势又是否真实可信。我们一起来验证一下。

首先我们定义基本的数据结构：

```
// 代表互斥锁
type FooMap struct {
 sync.Mutex
 data map[int]int
}

// 代表读写锁
type BarRwMap struct {
 sync.RWMutex
 data map[int]int
}

var fooMap *FooMap
var barRwMap *BarRwMap
var syncMap *sync.Map

// 初始化基本数据结构
func init() {
 fooMap = &FooMap{data: make(map[int]int, 100)}
 barRwMap = &BarRwMap{data: make(map[int]int, 100)}
 syncMap = &sync.Map{}
}

```

在配套方法上，常见的增删改查动作我们都编写了相应的方法。用于后续的压测（只展示部分代码）：

```
func builtinRwMapStore(k, v int) {
 barRwMap.Lock()
 defer barRwMap.Unlock()
 barRwMap.data[k] = v
}

func builtinRwMapLookup(k int) int {
 barRwMap.RLock()
 defer barRwMap.RUnlock()
 if v, ok := barRwMap.data[k]; !ok {
  return -1
 } else {
  return v
 }
}

func builtinRwMapDelete(k int) {
 barRwMap.Lock()
 defer barRwMap.Unlock()
 if _, ok := barRwMap.data[k]; !ok {
  return
 } else {
  delete(barRwMap.data, k)
 }
}

```

其余的类型方法基本类似，考虑重复篇幅问题因此就不在此展示了。

压测方法基本代码如下：

```
func BenchmarkBuiltinRwMapDeleteParalell(b *testing.B) {
 b.RunParallel(func(pb *testing.PB) {
  r := rand.New(rand.NewSource(time.Now().Unix()))
  for pb.Next() {
   k := r.Intn(100000000)
   builtinRwMapDelete(k)
  }
 })
}

```

这块主要就是增删改查的代码和压测方法的准备，压测代码直接复用的是大白大佬的 go19-examples/benchmark-for-map 项目。

也可以使用 Go 官方提供的 map\_bench\_test.go，有兴趣的小伙伴可以自己拉下来运行试一下。

### 压测结果

1）写入：

| 方法名 | 含义 | 压测结果 |
| --- | --- | --- |
| BenchmarkBuiltinMapStoreParalell-4 | map+mutex 写入元素 | 237.1 ns/op |
| BenchmarkSyncMapStoreParalell-4 | sync.map 写入元素 | 509.3 ns/op |
| BenchmarkBuiltinRwMapStoreParalell-4 | map+rwmutex 写入元素 | 207.8 ns/op |

在写入元素上，最慢的是 `sync.map` 类型，其次是原生 map+互斥锁（Mutex），最快的是原生 map+读写锁（RwMutex）。

总体的排序（从慢到快）为：SyncMapStore < MapStore < RwMapStore。

2）查找：

| 方法名 | 含义 | 压测结果 |
| --- | --- | --- |
| BenchmarkBuiltinMapLookupParalell-4 | map+mutex 查找元素 | 166.7 ns/op |
| BenchmarkBuiltinRwMapLookupParalell-4 | map+rwmutex 查找元素 | 60.49 ns/op |
| BenchmarkSyncMapLookupParalell-4 | sync.map 查找元素 | 53.39 ns/op |

在查找元素上，最慢的是原生 map+互斥锁，其次是原生 map+读写锁。最快的是 `sync.map` 类型。

总体的排序为：MapLookup < RwMapLookup < SyncMapLookup。

3）删除：

| 方法名 | 含义 | 压测结果 |
| --- | --- | --- |
| BenchmarkBuiltinMapDeleteParalell-4 | map+mutex 删除元素 | 168.3 ns/op |
| BenchmarkBuiltinRwMapDeleteParalell-4 | map+rwmutex 删除元素 | 188.5 ns/op |
| BenchmarkSyncMapDeleteParalell-4 | sync.map 删除元素 | 41.54 ns/op |

在删除元素上，最慢的是原生 map+读写锁，其次是原生 map+互斥锁，最快的是 `sync.map` 类型。

总体的排序为：RwMapDelete < MapDelete < SyncMapDelete。

### 场景分析

根据上述的压测结果，我们可以得出 `sync.Map` 类型：

*   在读和删场景上的性能是最佳的，领先一倍有多。
    
*   在写入场景上的性能非常差，落后原生 map+锁整整有一倍之多。
    

因此在实际的业务场景中。假设是读多写少的场景，会更建议使用 `sync.Map` 类型。

但若是那种写多的场景，例如多 goroutine 批量的循环写入，那就建议另辟途径了，性能不忍直视（无性能要求另当别论）。

sync.Map 剖析
-----------

清楚如何测试，测试的结果后。我们需要进一步深挖，知其所以然。

为什么 `sync.Map` 类型的测试结果这么的 “偏科”，为什么读操作性能这么高，写操作性能低的可怕，他是怎么设计的？

### 数据结构

`sync.Map` 类型的底层数据结构如下：

```
type Map struct {
 mu Mutex
 read atomic.Value // readOnly
 dirty map[interface{}]*entry
 misses int
}

// Map.read 属性实际存储的是 readOnly。
type readOnly struct {
 m       map[interface{}]*entry
 amended bool
}

```

*   mu：互斥锁，用于保护 read 和 dirty。
    
*   read：只读数据，支持并发读取（atomic.Value 类型）。如果涉及到更新操作，则只需要加锁来保证数据安全。
    

*   read 实际存储的是 readOnly 结构体，内部也是一个原生 map，amended 属性用于标记 read 和 dirty 的数据是否一致。
    

*   dirty：读写数据，是一个原生 map，也就是非线程安全。操作 dirty 需要加锁来保证数据安全。
    
*   misses：统计有多少次读取 read 没有命中。每次 read 中读取失败后，misses 的计数值都会加 1。
    

在 read 和 dirty 中，都有涉及到的结构体：

```
type entry struct {
 p unsafe.Pointer // *interface{}
}

```

其包含一个指针 p, 用于指向用户存储的元素（key）所指向的 value 值。

在此建议你必须搞懂 read、dirty、entry，再往下看，食用效果会更佳，后续会围绕着这几个概念流转。

### 查找过程

划重点，Map 类型本质上是有两个 “map”。一个叫 read、一个叫 dirty，长的也差不多：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/3a34f8cbe34f428c93bddfa7d302a2bb~tplv-k3u1fbpfcp-zoom-1.image)

sync.Map 的 2 个 map

当我们从 sync.Map 类型中读取数据时，其会先查看 read 中是否包含所需的元素：

*   若有，则通过 atomic 原子操作读取数据并返回。
    
*   若无，则会判断 `read.readOnly` 中的 amended 属性，他会告诉程序 dirty 是否包含 `read.readOnly.m` 中没有的数据；因此若存在，也就是 amended 为 true，将会进一步到 dirty 中查找数据。
    

sync.Map 的读操作性能如此之高的原因，就在于存在 read 这一巧妙的设计，其作为一个缓存层，提供了快路径（fast path）的查找。

同时其结合 amended 属性，配套解决了每次读取都涉及锁的问题，实现了读这一个使用场景的高性能。

### 写入过程

我们直接关注 `sync.Map` 类型的 Store 方法，该方法的作用是新增或更新一个元素。

源码如下：

```
func (m *Map) Store(key, value interface{}) {
 read, _ := m.read.Load().(readOnly)
 if e, ok := read.m[key]; ok && e.tryStore(&value) {
  return
 }
  ...
}

```

调用 `Load` 方法检查 `m.read` 中是否存在这个元素。若存在，且没有被标记为删除状态，则尝试存储。

若该元素不存在或已经被标记为删除状态，则继续走到下面流程：

```
func (m *Map) Store(key, value interface{}) {
 ...
 m.mu.Lock()
 read, _ = m.read.Load().(readOnly)
 if e, ok := read.m[key]; ok {
  if e.unexpungeLocked() {
   m.dirty[key] = e
  }
  e.storeLocked(&value)
 } else if e, ok := m.dirty[key]; ok {
  e.storeLocked(&value)
 } else {
  if !read.amended {
   m.dirtyLocked()
   m.read.Store(readOnly{m: read.m, amended: true})
  }
  m.dirty[key] = newEntry(value)
 }
 m.mu.Unlock()
}

```

由于已经走到了 dirty 的流程，因此开头就直接调用了 `Lock` 方法**上互斥锁**，保证数据安全，也是凸显**性能变差的第一幕**。

其分为以下三个处理分支：

*   若发现 read 中存在该元素，但已经被标记为已删除（expunged），则说明 dirty 不等于 nil（dirty 中肯定不存在该元素）。其将会执行如下操作。
    

*   将元素状态从已删除（expunged）更改为 nil。
    
*   将元素插入 dirty 中。
    

*   若发现 read 中不存在该元素，但 dirty 中存在该元素，则直接写入更新 entry 的指向。
    
*   若发现 read 和 dirty 都不存在该元素，则从 read 中复制未被标记删除的数据，并向 dirty 中插入该元素，赋予元素值 entry 的指向。
    

我们理一理，写入过程的整体流程就是：

*   查 read，read 上没有，或者已标记删除状态。
    
*   上互斥锁（Mutex）。
    
*   操作 dirty，根据各种数据情况和状态进行处理。
    

回到最初的话题，为什么他写入性能差那么多。究其原因：

*   写入一定要会经过 read，无论如何都比别人多一层，后续还要查数据情况和状态，性能开销相较更大。
    
*   （第三个处理分支）当初始化或者 dirty 被提升后，会从 read 中复制全量的数据，若 read 中数据量大，则会影响性能。
    

可得知 `sync.Map` 类型不适合写多的场景，读多写少是比较好的。

若有大数据量的场景，则需要考虑 read 复制数据时的偶然性能抖动是否能够接受。

### 删除过程

这时候可能有小伙伴在想了。写入过程，理论上和删除不会差太远。怎么 `sync.Map` 类型的删除的性能似乎还行，这里面有什么猫腻？

源码如下：

```
func (m *Map) LoadAndDelete(key interface{}) (value interface{}, loaded bool) {
 read, _ := m.read.Load().(readOnly)
 e, ok := read.m[key]
 ...
  if ok {
  return e.delete()
 }
}

```

删除是标准的开场，依然先到 read 检查该元素是否存在。

若存在，则调用 `delete` 标记为 expunged（删除状态），非常高效。可以明确在 read 中的元素，被删除，性能是非常好的。

若不存在，也就是走到 dirty 流程中：

```
func (m *Map) LoadAndDelete(key interface{}) (value interface{}, loaded bool) {
 ...
 if !ok && read.amended {
  m.mu.Lock()
  read, _ = m.read.Load().(readOnly)
  e, ok = read.m[key]
  if !ok && read.amended {
   e, ok = m.dirty[key]
   delete(m.dirty, key)
   m.missLocked()
  }
  m.mu.Unlock()
 }
 ...
 return nil, false
}

```

若 read 中不存在该元素，dirty 不为空，read 与 dirty 不一致（利用 amended 判别），则表明要操作 dirty，上互斥锁。

再重复进行双重检查，若 read 仍然不存在该元素。则调用 delete 方法从 dirty 中标记该元素的删除。

需要注意，出现频率较高的 delete 方法：

```
func (e *entry) delete() (value interface{}, ok bool) {
 for {
  p := atomic.LoadPointer(&e.p)
  if p == nil || p == expunged {
   return nil, false
  }
  if atomic.CompareAndSwapPointer(&e.p, p, nil) {
   return *(*interface{})(p), true
  }
 }
}

```

该方法都是将 entry.p 置为 nil，并且标记为 expunged（删除状态），而**不是真真正正的删除**。

注：不要误用 `sync.Map`，前段时间从字节大佬分享的案例来看，他们将一个连接作为 key 放了进去，于是和这个连接相关的，例如：buffer 的内存就永远无法释放了...

总结
--

通过阅读本文，我们明确了 `sync.Map` 和原生 map +互斥锁/读写锁之间的性能情况。

标准库 `sync.Map` 虽说支持并发读写 map，但更适用于读多写少的场景，因为他写入的性能比较差，使用时要考虑清楚这一点。

另外我们针对 `sync.Map` 的性能差异，进行了深入的源码剖析，了解到了其背后快、慢的原因，实现了知其然知其所以然。

经常看到并发读写 map 导致致命错误，实在是令人忧心。大家觉得如果本文不错，欢迎分享给更多的 Go 爱好者 ：）

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，欢迎 Star 催更。


参考
--

*   Package sync
    
*   踩了 Golang sync.Map 的一个坑
    
*   go19-examples/benchmark-for-map
    
*   通过实例深入理解sync.Map的工作原理
    

================================================
FILE: content/posts/go/talk/2018-03-13-golang-relatively-path.md
================================================
---

title:      "聊一聊，Go 的相对路径问题"
date:       2018-03-13 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

## 前言

`Golang` 中存在各种运行方式，如何**正确的引用文件路径**成为一个值得商议的问题

以 [gin-blog](https://github.com/EDDYCJY/go-gin-example) 为例，当我们在项目根目录下，执行 `go run main.go` 时能够正常运行（`go build`也是正常的）
```
[$ gin-blog]# go run main.go
[GIN-debug] [WARNING] Running in "debug" mode. Switch to "release" mode in production.
 - using env:    export GIN_MODE=release
 - using code:    gin.SetMode(gin.ReleaseMode)

[GIN-debug] GET    /api/v1/tags              --> gin-blog/routers/api/v1.GetTags (3 handlers)
...
```


那么在不同的目录层级下，不同的方式运行，又是怎么样的呢，带着我们的疑问去学习

## 问题
1、 go run
我们上移目录层级，到 `$GOPATH/src` 下，执行 `go run gin-blog/main.go`
```
[$ src]# go run gin-blog/main.go
2018/03/12 16:06:13 Fail to parse 'conf/app.ini': open conf/app.ini: no such file or directory
exit status 1
```

2、 go build，执行 `./gin-blog/main`
```
[$ src]# ./gin-blog/main
2018/03/12 16:49:35 Fail to parse 'conf/app.ini': open conf/app.ini: no such file or directory
```

这时候你要打一个大大的问号，就是我的程序读取到什么地方去了

--- 

我们通过分析得知，**`Golang`的相对路径是相对于执行命令时的目录**；自然也就读取不到了


## 思考

既然已经知道问题的所在点，我们就可以寻思做点什么 : )

我们想到相对路径是相对执行命令的目录，那么我们获取可执行文件的地址，拼接起来不就好了吗？

## 实践

我们编写**获取当前可执行文件路径的方法**
```
import (
	"path/filepath"
	"os"
	"os/exec"
	"string"
)

func GetAppPath() string {
    file, _ := exec.LookPath(os.Args[0])
    path, _ := filepath.Abs(file)
    index := strings.LastIndex(path, string(os.PathSeparator))

    return path[:index]
}
```
将其放到启动代码处查看路径
```
log.Println(GetAppPath())
```

我们分别执行以下两个命令，查看输出结果
1、 go run 
```
$ go run main.go
2018/03/12 18:45:40 /tmp/go-build962610262/b001/exe
```
2、 go build
```
$ ./main
2018/03/12 18:49:44 $GOPATH/src/gin-blog

```

## 剖析

我们聚焦在 `go run` 的输出结果上，发现它是一个临时文件的地址，这是为什么呢？

在`go help run`中，我们可以看到
```
Run compiles and runs the main package comprising the named Go source files.
A Go source file is defined to be a file ending in a literal ".go" suffix.
```

也就是 `go run` 执行时会将文件放到 `/tmp/go-build...` 目录下，编译并运行

因此`go run main.go`出现`/tmp/go-build962610262/b001/exe`结果也不奇怪了，因为它已经跑到临时目录下去执行可执行文件了

---

这就已经很清楚了，那么我们想想，会出现哪些问题呢

- 依赖相对路径的文件，出现路径出错的问题
- `go run` 和 `go build` 不一样，一个到临时目录下执行，一个可手动在编译后的目录下执行，路径的处理方式会不同
- 不断`go run`，不断产生新的临时文件


这其实就是**根本原因**了，因为 `go run` 和 `go build` 的编译文件执行路径并不同，执行的层级也有可能不一样，自然而然就出现各种读取不到的奇怪问题了


## 解决方案

**一、获取编译后的可执行文件路径**

1、 将配置文件的相对路径与`GetAppPath()`的结果相拼接，可解决`go build main.go`的可执行文件跨目录执行的问题（如：`./src/gin-blog/main`）
```
import (
	"path/filepath"
	"os"
	"os/exec"
	"string"
)

func GetAppPath() string {
    file, _ := exec.LookPath(os.Args[0])
    path, _ := filepath.Abs(file)
    index := strings.LastIndex(path, string(os.PathSeparator))

    return path[:index]
}
```

但是这种方式，对于`go run`依旧无效，这时候就需要2来补救

2、 通过传递参数指定路径，可解决`go run`的问题
```
package main

import (
    "flag"
    "fmt"
)

func main() {
    var appPath string
    flag.StringVar(&appPath, "app-path", "app-path")
    flag.Parse()
    fmt.Printf("App path: %s", appPath)
}
```
运行
```
go run main.go --app-path "Your project address"
```

**二、增加`os.Getwd()`进行多层判断**

参见 [beego](https://github.com/astaxie/beego/blob/master/config.go#L133-L146) 读取 `app.conf` 的代码

该写法可兼容 `go build` 和在项目根目录执行 `go run` ，但是若跨目录执行 `go run` 就不行


**三、配置全局系统变量**

我们可以通过`os.Getenv`来获取系统全局变量，然后与相对路径进行拼接

1、 设置项目工作区

简单来说，就是设置项目（应用）的工作路径，然后与配置文件、日志文件等相对路径进行拼接，达到相对的绝对路径来保证路径一致

参见 [gogs](https://github.com/gogits/gogs/blob/master/pkg/setting/setting.go#L351) 读取`GOGS_WORK_DIR`进行拼接的代码

2、 利用系统自带变量

简单来说就是通过系统自带的全局变量，例如`$HOME`等，将配置文件存放在`$HOME/conf`或`/etc/conf`下

这样子就能更加固定的存放配置文件，**不需要额外去设置一个环境变量**

（这点今早与一位SFer讨论了一波，感谢）

## 拓展

`go test` 在一些场景下也会遇到路径问题，因为`go test`只能够在当前目录执行，所以在执行测试用例的时候，你的执行目录已经是测试目录了

需要注意的是，如果采用获取外部参数的办法，用 `os.args` 时，`go test -args` 和 `go run`、`go build` 会有命令行参数位置的不一致问题

## 小结

这三种解决方案，在目前可见的开源项目或介绍中都能找到这些的身影

优缺点也是显而易见的，我认为应在**不同项目选定合适的解决方案**即可

建议大家不要强依赖读取配置文件的模块，应当将其“堆积木”化，**需要什么配置才去注册什么配置变量**，可以解决一部分的问题

大家又有什么想法呢，一起讨论一波？



================================================
FILE: content/posts/go/talk/2018-05-21-go-fake-useragent.md
================================================
---

title:      "Go 的 fake-useragent 了解一下"
date:       2018-05-21 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

有的网站会根据 User-Agent 的不同，跳转到不同（PC、M）的站点，也有根据版本的不同给出不一样的提示等等，而 User-Agent 的变化更是爬虫里的基础姿势

使用 Go 编写网络爬虫或需要模拟浏览器头（User-Agent）的时候，你是否会觉得很麻烦，获取请求头（Request Headers）的 User-Agent 还得找来找去，挺繁琐。先前我也遇到了这个问题，因此有了这个项目 [fake-useragent](https://github.com/EDDYCJY/fake-useragent)，用来解决你我的痛点

项目地址：https://github.com/EDDYCJY/fake-useragent

## 支持

- All User-Agent Random
- Chrome
- InternetExplorer (IE)
- Firefox
- Safari
- Android
- MacOSX
- IOS
- Linux
- IPhone
- IPad
- Computer
- Mobile

## 安装

```
$ go get github.com/EDDYCJY/fake-useragent
```

## 用法

``` go
package main

import (
	"log"

	"github.com/EDDYCJY/fake-useragent"
)

func main() {
	// 推荐使用
	random := browser.Random()
	log.Printf("Random: %s", random)

	chrome := browser.Chrome()
	log.Printf("Chrome: %s", chrome)

	internetExplorer := browser.InternetExplorer()
	log.Printf("IE: %s", internetExplorer)

	firefox := browser.Firefox()
	log.Printf("Firefox: %s", firefox)

	safari := browser.Safari()
	log.Printf("Safari: %s", safari)

	android := browser.Android()
	log.Printf("Android: %s", android)

	macOSX := browser.MacOSX()
	log.Printf("MacOSX: %s", macOSX)

	ios := browser.IOS()
	log.Printf("IOS: %s", ios)

	linux := browser.Linux()
	log.Printf("Linux: %s", linux)

	iphone := browser.IPhone()
	log.Printf("IPhone: %s", iphone)

	ipad := browser.IPad()
	log.Printf("IPad: %s", ipad)

	computer := browser.Computer()
	log.Printf("Computer: %s", computer)

	mobile := browser.Mobile()
	log.Printf("Mobile: %s", mobile)
}
```

### 定制

你可以调整抓取数据源的最大页数、时间间隔以及最大超时时间。 如果不填写，则为默认值。

``` go
client := browser.Client{
	MaxPage: 3,
	Delay: 200 * time.Millisecond,
	Timeout: 10 * time.Second,
}
cache := browser.Cache{}
b := browser.NewBrowser(client, cache)

random := b.Random()
```

更新浏览器头的临时文件缓存

``` go
client := browser.Client{}
cache := browser.Cache{
	UpdateFile: true,
}
b := browser.NewBrowser(client, cache)
```
**最后，建议常规用法就好，默认参数能够满足日常需求**

## 输出

``` sh
Random: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_13_2) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.132 Safari/537.36

Chrome: Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/60.0.3112.113 Safari/537.36

IE: Mozilla/5.0 (compatible; MSIE 9.0; Windows NT 6.1; WOW64; Trident/5.0)

Firefox: Mozilla/5.0 (Windows NT 6.3; WOW64; rv:41.0) Gecko/20100101 Firefox/41.0

Safari: Mozilla/5.0 (iPhone; CPU iPhone OS 11_2_5 like Mac OS X) AppleWebKit/604.5.6 (KHTML, like Gecko) Version/11.0 Mobile/15D60 Safari/604.1

Android: Mozilla/5.0 (Linux; Android 6.0; MYA-L22 Build/HUAWEIMYA-L22) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/62.0.3202.84 Mobile Safari/537.36

MacOSX: Mozilla/5.0 (Macintosh; Intel Mac OS X 10_10_5) AppleWebKit/602.2.14 (KHTML, like Gecko) Version/10.0.1 Safari/602.2.14

IOS: Mozilla/5.0 (iPhone; CPU iPhone OS 10_1 like Mac OS X) AppleWebKit/602.2.14 (KHTML, like Gecko) Version/10.0 Mobile/14B72 Safari/602.1

Linux: Mozilla/5.0 (X11; Linux x86_64; rv:42.0) Gecko/20100101 Firefox/42.0

IPhone: Mozilla/5.0 (iPhone; CPU iPhone OS 10_2 like Mac OS X) AppleWebKit/602.3.12 (KHTML, like Gecko) Version/10.0 Mobile/14C92 Safari/602.1

IPad: Mozilla/5.0 (iPad; CPU OS 5_0_1 like Mac OS X) AppleWebKit/534.46 (KHTML, like Gecko) Version/5.1 Mobile/9A405 Safari/7534.48.3

Computer: Mozilla/5.0 (Windows NT 10.0; WOW64; rv:54.0) Gecko/20100101 Firefox/54.0

Mobile: Mozilla/5.0 (Linux; Android 7.0; Redmi Note 4 Build/NRD90M) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/63.0.3239.111 Mobile Safari/537.36
```

## 注意

如果第一次使用，[fake-useragent](https://github.com/EDDYCJY/fake-useragent) 将收集数据并在临时目录中创建一个文件作为文件缓存，请耐心等待几秒钟

## 最后

如果在项目中发现了什么问题，欢迎提交 PR 或者 issue。希望你能够喜欢这个项目，根本目的还是为了解决痛点，欢迎 Star！😁

---

项目地址：https://github.com/EDDYCJY/fake-useragent



================================================
FILE: content/posts/go/talk/2018-06-07-go-redis-protocol.md
================================================
---

title:      "用 Go 来了解一下 Redis 通讯协议"
date:       2018-06-07 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

Go、PHP、Java... 都有那么多包来支撑你使用 Redis，那你是否有想过

有了服务端，有了客户端，他们俩是怎样通讯，又是基于什么通讯协议做出交互的呢？

## 介绍

基于我们的目的，本文主要讲解和实践 Redis 的通讯协议

Redis 的客户端和服务端是通过 TCP 连接来进行数据交互， 服务器默认的端口号为 6379

客户端和服务器发送的命令或数据一律以 \r\n （CRLF）结尾（这是一条约定）

## 协议

在 Redis 中分为**请求**和**回复**，而请求协议又分为新版和旧版，新版统一请求协议在 Redis 1.2 版本中引入，最终在 Redis 2.0 版本成为 Redis 服务器通信的标准方式

本文是基于新版协议来实现功能，不建议使用旧版（1.2 挺老旧了）。如下是新协议的各种范例：

### 请求协议

1、 格式示例

```
*<参数数量> CR LF
$<参数 1 的字节数量> CR LF
<参数 1 的数据> CR LF
...
$<参数 N 的字节数量> CR LF
<参数 N 的数据> CR LF
```

在该协议下所有发送至 Redis 服务器的参数都是二进制安全（binary safe）的

2、打印示例

```
*3
$3
SET
$5
mykey
$7
myvalue
```

3、实际协议值

```
"*3\r\n$3\r\nSET\r\n$5\r\nmykey\r\n$7\r\nmyvalue\r\n"
```

这就是 Redis 的请求协议规范，按照范例1编写客户端逻辑，最终发送的是范例3，相信你已经有大致的概念了，Redis 的协议非常的简洁易懂，这也是好上手的原因之一，你可以想想协议这么定义的好处在哪？

### 回复

Redis 会根据你请求协议的不同（执行的命令结果也不同），返回多种不同类型的回复。在这个回复“协议”中，可以通过检查第一个字节，确定这个回复是什么类型，如下：

- 状态回复（status reply）的第一个字节是 "+"
- 错误回复（error reply）的第一个字节是 "-"
- 整数回复（integer reply）的第一个字节是 ":"
- 批量回复（bulk reply）的第一个字节是 "$"
- 多条批量回复（multi bulk reply）的第一个字节是 "*"


有了回复的头部标识，结尾的 CRLF，你可以大致猜想出回复“协议”是怎么样的，但是实践才能得出真理，斎知道怕是你很快就忘记了 😀


## 实践

### 与 Redis 服务器交互

```
package main

import (
	"log"
	"net"
	"os"

	"github.com/EDDYCJY/redis-protocol-example/protocol"
)

const (
	Address = "127.0.0.1:6379"
	Network = "tcp"
)

func Conn(network, address string) (net.Conn, error) {
	conn, err := net.Dial(network, address)
	if err != nil {
		return nil, err
	}

	return conn, nil
}

func main() {
        // 读取入参
	args := os.Args[1:]
	if len(args) <= 0 {
		log.Fatalf("Os.Args <= 0")
	}
    
        // 获取请求协议
	reqCommand := protocol.GetRequest(args)
	
	// 连接 Redis 服务器
	redisConn, err := Conn(Network, Address)
	if err != nil {
		log.Fatalf("Conn err: %v", err)
	}
	defer redisConn.Close()
    
        // 写入请求内容
	_, err = redisConn.Write(reqCommand)
	if err != nil {
		log.Fatalf("Conn Write err: %v", err)
	}
    
        // 读取回复
	command := make([]byte, 1024)
	n, err := redisConn.Read(command)
	if err != nil {
		log.Fatalf("Conn Read err: %v", err)
	}
    
        // 处理回复
	reply, err := protocol.GetReply(command[:n])
	if err != nil {
		log.Fatalf("protocol.GetReply err: %v", err)
	}
    
        // 处理后的回复内容
	log.Printf("Reply: %v", reply)
	// 原始的回复内容
	log.Printf("Command: %v", string(command[:n]))
}
```

在这里我们完成了整个 Redis 客户端和服务端交互的流程，分别如下：

1、读取命令行参数：获取执行的 Redis 命令

2、获取请求协议参数

3、连接 Redis 服务器，获取连接句柄

4、将请求协议参数写入连接：发送请求的命令行参数

5、从连接中读取返回的数据：读取先前请求的回复数据

6、根据回复“协议”内容，处理回复的数据集

7、输出处理后的回复内容及原始回复内容

### 请求

```
func GetRequest(args []string) []byte {
	req := []string{
		"*" + strconv.Itoa(len(args)),
	}

	for _, arg := range args {
		req = append(req, "$"+strconv.Itoa(len(arg)))
		req = append(req, arg)
	}

	str := strings.Join(req, "\r\n")
	return []byte(str + "\r\n")
}
```

通过对 Redis 的请求协议的分析，可得出它的规律，先加上标志位，计算参数总数量，再循环合并各个参数的字节数量、值就可以了

### 回复

```
func GetReply(reply []byte) (interface{}, error) {
	replyType := reply[0]
	switch replyType {
	case StatusReply:
		return doStatusReply(reply[1:])
	case ErrorReply:
		return doErrorReply(reply[1:])
	case IntegerReply:
		return doIntegerReply(reply[1:])
	case BulkReply:
		return doBulkReply(reply[1:])
	case MultiBulkReply:
		return doMultiBulkReply(reply[1:])
	default:
		return nil, nil
	}
}

func doStatusReply(reply []byte) (string, error) {
	if len(reply) == 3 && reply[1] == 'O' && reply[2] == 'K' {
		return OkReply, nil
	}

	if len(reply) == 5 && reply[1] == 'P' && reply[2] == 'O' && reply[3] == 'N' && reply[4] == 'G' {
		return PongReply, nil
	}

	return string(reply), nil
}

func doErrorReply(reply []byte) (string, error) {
	return string(reply), nil
}

func doIntegerReply(reply []byte) (int, error) {
	pos := getFlagPos('\r', reply)
	result, err := strconv.Atoi(string(reply[:pos]))
	if err != nil {
		return 0, err
	}

	return result, nil
}

...
```

在这里我们对所有回复类型进行了分发，不同的回复标志位对应不同的处理方式，在这里需求注意几项问题，如下：

1、当请求的值不存在，会将特殊值 -1 用作回复

2、服务器发送的所有字符串都由 CRLF 结尾

3、多条批量回复是可基于批量回复的，要注意理解

4、无内容的多条批量回复是存在的

最重要的是，对不同回复的规则的把控，能够让你更好的理解 Redis 的请求、回复的交互过程 👌

## 小结

写这篇文章的起因，是因为常常在使用 Redis 时，只是用，你不知道它是基于什么样的通讯协议来通讯，这样的感觉是十分难受的

通过本文的讲解，我相信你已经大致了解 Redis 客户端是怎么样和服务端交互，也清楚了其所用的通讯原理，希望能够对你有所帮助！

最后，如果想详细查看代码，右拐项目地址：https://github.com/EDDYCJY/redis-protocol-example

如果对你有所帮助，欢迎点个 Star 👍

## 参考

- [通信协议](http://doc.redisfans.com/topic/protocol.html)


================================================
FILE: content/posts/go/talk/2018-11-25-gomock.md
================================================
---

title:      "使用 Gomock 进行单元测试"
date:       2018-11-25 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

在实际项目中，需要进行单元测试的时候。却往往发现有一大堆依赖项。这时候就是 [Gomock](https://github.com/golang/mock) 大显身手的时候了

Gomock 是 Go 语言的一个 mock 框架，官方的那种 🤪

## 安装

```
$ go get -u github.com/golang/mock/gomock
$ go install github.com/golang/mock/mockgen
```

1. 第一步：我们将安装 gomock 第三方库和 mock 代码的生成工具 mockgen。而后者可以大大的节省我们的工作量。只需要了解其使用方式就可以

2. 第二步：输入 `mockgen` 验证代码生成工具是否安装正确。若无法正常响应，请检查 `bin` 目录下是否包含该二进制文件

### 用法

在 `mockgen` 命令中，支持两种生成模式：

1. source：从源文件生成 mock 接口（通过 -source 启用）

```
mockgen -source=foo.go [other options]
```

2. reflect：通过使用反射程序来生成 mock 接口。它通过传递两个非标志参数来启用：导入路径和逗号分隔的接口列表

```
mockgen database/sql/driver Conn,Driver
```

从本质上来讲，两种方式生成的 mock 代码并没有什么区别。因此选择合适的就可以了

## 写测试用例

在本文将模拟一个简单 Demo 来编写测试用例，熟悉整体的测试流程

### 步骤

1. 想清楚整体逻辑
2. 定义想要（模拟）依赖项的 interface（接口）
3. 使用 `mockgen` 命令对所需 mock 的 interface 生成 mock 文件
4. 编写单元测试的逻辑，在测试中使用 mock
5. 进行单元测试的验证

### 目录

```
├── mock
├── person
│   └── male.go
└── user
    ├── user.go
    └── user_test.go
```

### 编写

#### interface 方法

打开 person/male.go 文件，写入以下内容：

```go
package person

type Male interface {
	Get(id int64) error
}
```

#### 调用方法

打开 user/user.go 文件，写入以下内容：

```go
package user

import "github.com/EDDYCJY/mockd/person"

type User struct {
	Person person.Male
}

func NewUser(p person.Male) *User {
	return &User{Person: p}
}

func (u *User) GetUserInfo(id int64) error {
	return u.Person.Get(id)
}
```

#### 生成 mock 文件

回到 `mockd/` 的根目录下，执行以下命令

```
$ mockgen -source=./person/male.go -destination=./mock/male_mock.go -package=mock
```

在执行完毕后，可以发现 `mock/` 目录下多出了 male_mock.go 文件，这就是 mock 文件。那么命令中的指令又分别有什么用呢？如下：

- -source：设置需要模拟（mock）的接口文件
- -destination：设置 mock 文件输出的地方，若不设置则打印到标准输出中
- -package：设置 mock 文件的包名，若不设置则为 `mock_` 前缀加上文件名（如本文的包名会为 mock_person）

想了解更多的指令符，可参见 [官方文档](https://github.com/golang/mock#running-mockgen)

##### 输出的 mock 文件

```go
// Code generated by MockGen. DO NOT EDIT.
// Source: ./person/male.go

// Package mock is a generated GoMock package.
package mock

import (
	gomock "github.com/golang/mock/gomock"
	reflect "reflect"
)

// MockMale is a mock of Male interface
type MockMale struct {
	ctrl     *gomock.Controller
	recorder *MockMaleMockRecorder
}

// MockMaleMockRecorder is the mock recorder for MockMale
type MockMaleMockRecorder struct {
	mock *MockMale
}

// NewMockMale creates a new mock instance
func NewMockMale(ctrl *gomock.Controller) *MockMale {
	mock := &MockMale{ctrl: ctrl}
	mock.recorder = &MockMaleMockRecorder{mock}
	return mock
}

// EXPECT returns an object that allows the caller to indicate expected use
func (m *MockMale) EXPECT() *MockMaleMockRecorder {
	return m.recorder
}

// Get mocks base method
func (m *MockMale) Get(id int64) error {
	ret := m.ctrl.Call(m, "Get", id)
	ret0, _ := ret[0].(error)
	return ret0
}

// Get indicates an expected call of Get
func (mr *MockMaleMockRecorder) Get(id interface{}) *gomock.Call {
	return mr.mock.ctrl.RecordCallWithMethodType(mr.mock, "Get", reflect.TypeOf((*MockMale)(nil).Get), id)
}
```

#### 测试用例

打开 user/user_test.go 文件，写入以下内容：

```go
package user

import (
	"testing"

	"github.com/EDDYCJY/mockd/mock"

	"github.com/golang/mock/gomock"
)

func TestUser_GetUserInfo(t *testing.T) {
	ctl := gomock.NewController(t)
	defer ctl.Finish()

	var id int64 = 1
	mockMale := mock.NewMockMale(ctl)
	gomock.InOrder(
		mockMale.EXPECT().Get(id).Return(nil),
	)

	user := NewUser(mockMale)
	err := user.GetUserInfo(id)
	if err != nil {
		t.Errorf("user.GetUserInfo err: %v", err)
	}
}
```

1. gomock.NewController：返回 `gomock.Controller`，它代表 mock 生态系统中的顶级控件。定义了 mock 对象的范围、生命周期和期待值。另外它在多个 goroutine 中是安全的
2. mock.NewMockMale：创建一个新的 mock 实例
3. gomock.InOrder：声明给定的调用应按顺序进行（是对 gomock.After 的二次封装）
4. mockMale.EXPECT().Get(id).Return(nil)：这里有三个步骤，`EXPECT()`返回一个允许调用者设置**期望**和**返回值**的对象。`Get(id)` 是设置入参并调用 mock 实例中的方法。`Return(nil)` 是设置先前调用的方法出参。简单来说，就是设置入参并调用，最后设置返回值

5. NewUser(mockMale)：创建 User 实例，值得注意的是，在这里**注入了 mock 对象**，因此实际在随后的 `user.GetUserInfo(id)` 调用（入参：id 为 1）中。它调用的是我们事先模拟好的 mock 方法
6. ctl.Finish()：进行 mock 用例的期望值断言，一般会使用 `defer` 延迟执行，以防止我们忘记这一操作

### 测试

回到 `mockd/` 的根目录下，执行以下命令

```
$ go test ./user
ok  	github.com/EDDYCJY/mockd/user
```

看到这样的结果，就大功告成啦！你可以自己调整一下 `Return()` 的返回值，以此得到不一样的测试结果哦 😄

## 查看测试情况

### 测试覆盖率

```
$ go test -cover ./user
ok  	github.com/EDDYCJY/mockd/user	(cached)	coverage: 100.0% of statements
```

可通过设置 `-cover` 标志符来开启覆盖率的统计，展示内容为 `coverage: 100.0%`。

### 可视化界面

1. 生成测试覆盖率的 profile 文件

```
$ go test ./... -coverprofile=cover.out
```

2. 利用 profile 文件生成可视化界面

```
$ go tool cover -html=cover.out
```

3. 查看可视化界面，分析覆盖情况

![image](https://s2.ax1x.com/2020/02/27/3wKu7R.jpg)

## 更多

### 一、常用 mock 方法

#### 调用方法

- Call.Do()：声明在匹配时要运行的操作
- Call.DoAndReturn()：声明在匹配调用时要运行的操作，并且模拟返回该函数的返回值
- Call.MaxTimes()：设置最大的调用次数为 n 次
- Call.MinTimes()：设置最小的调用次数为 n 次
- Call.AnyTimes()：允许调用次数为 0 次或更多次
- Call.Times()：设置调用次数为 n 次

#### 参数匹配

- gomock.Any()：匹配任意值
- gomock.Eq()：通过反射匹配到指定的类型值，而不需要手动设置
- gomock.Nil()：返回 nil

建议更多的方法可参见 [官方文档](https://godoc.org/github.com/golang/mock/gomock#pkg-index)

### 二、生成多个 mock 文件

你可能会想一条条命令生成 mock 文件，岂不得崩溃？

当然，官方提供了更方便的方式，我们可以利用 `go:generate` 来完成批量处理的功能

```
go generate [-run regexp] [-n] [-v] [-x] [build flags] [file.go... | packages]
```

#### 修改 interface 方法

打开 person/male.go 文件，修改为以下内容：

```go
package person

//go:generate mockgen -destination=../mock/male_mock.go -package=mock github.com/EDDYCJY/mockd/person Male

type Male interface {
	Get(id int64) error
}
```

我们关注到 `go:generate` 这条语句，可分为以下部分：

1. 声明 `//go:generate` （注意不要留空格）
2. 使用 `mockgen` 命令
3. 定义 `-destination`
4. 定义 `-package`
5. 定义 `source`，此处为 person 的包路径
6. 定义 `interfaces`，此处为 `Male`

#### 重新生成 mock 文件

回到 `mockd/` 的根目录下，执行以下命令

```
$ go generate ./...
```

再检查 `mock/` 发现也已经正确生成了，在多个文件时是不是很方便呢 🤩

## 总结

在单元测试这一环，gomock 给我们提供了极大的便利。能够 mock 掉许许多多的依赖项

其中还有很多的使用方式和功能。你可以 mark 住后详细阅读下官方文档，记忆会更深刻

================================================
FILE: content/posts/go/talk/2018-12-26-go-memory-align.md
================================================
---

title:      "在 Go 中恰到好处的内存对齐"
date:       2018-12-26 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://s2.ax1x.com/2020/02/27/3wuT0A.png)

## 问题

```go
type Part1 struct {
	a bool
	b int32
	c int8
	d int64
	e byte
}
```

在开始之前，希望你计算一下 `Part1` 共占用的大小是多少呢？

```go
func main() {
	fmt.Printf("bool size: %d\n", unsafe.Sizeof(bool(true)))
	fmt.Printf("int32 size: %d\n", unsafe.Sizeof(int32(0)))
	fmt.Printf("int8 size: %d\n", unsafe.Sizeof(int8(0)))
	fmt.Printf("int64 size: %d\n", unsafe.Sizeof(int64(0)))
	fmt.Printf("byte size: %d\n", unsafe.Sizeof(byte(0)))
	fmt.Printf("string size: %d\n", unsafe.Sizeof("EDDYCJY"))
}
```

输出结果：

```
bool size: 1
int32 size: 4
int8 size: 1
int64 size: 8
byte size: 1
string size: 16
```

这么一算，`Part1` 这一个结构体的占用内存大小为 1+4+1+8+1 = 15 个字节。相信有的小伙伴是这么算的，看上去也没什么毛病

真实情况是怎么样的呢？我们实际调用看看，如下：

```go
type Part1 struct {
	a bool
	b int32
	c int8
	d int64
	e byte
}

func main() {
	part1 := Part1{}

	fmt.Printf("part1 size: %d, align: %d\n", unsafe.Sizeof(part1), unsafe.Alignof(part1))
}
```

输出结果：

```
part1 size: 32, align: 8
```

最终输出为占用 32 个字节。这与前面所预期的结果完全不一样。这充分地说明了先前的计算方式是错误的。为什么呢？

在这里要提到 “内存对齐” 这一概念，才能够用正确的姿势去计算，接下来我们详细的讲讲它是什么

## 内存对齐

有的小伙伴可能会认为内存读取，就是一个简单的字节数组摆放

![image](https://s2.ax1x.com/2020/02/27/3wuLff.png)

上图表示一个坑一个萝卜的内存读取方式。但实际上 CPU 并不会以一个一个字节去读取和写入内存。相反 CPU 读取内存是**一块一块读取**的，块的大小可以为 2、4、6、8、16 字节等大小。块大小我们称其为**内存访问粒度**。如下图：

![image](https://s2.ax1x.com/2020/02/27/3wKSmj.png)

在样例中，假设访问粒度为 4。 CPU 是以每 4 个字节大小的访问粒度去读取和写入内存的。这才是正确的姿势

### 为什么要关心对齐

- 你正在编写的代码在性能（CPU、Memory）方面有一定的要求
- 你正在处理向量方面的指令
- 某些硬件平台（ARM）体系不支持未对齐的内存访问

另外作为一个工程师，你也很有必要学习这块知识点哦 :)

### 为什么要做对齐

- 平台（移植性）原因：不是所有的硬件平台都能够访问任意地址上的任意数据。例如：特定的硬件平台只允许在特定地址获取特定类型的数据，否则会导致异常情况
- 性能原因：若访问未对齐的内存，将会导致 CPU 进行两次内存访问，并且要花费额外的时钟周期来处理对齐及运算。而本身就对齐的内存仅需要一次访问就可以完成读取动作

![image](https://s2.ax1x.com/2020/02/27/3wKApT.png)

在上图中，假设从 Index 1 开始读取，将会出现很崩溃的问题。因为它的内存访问边界是不对齐的。因此 CPU 会做一些额外的处理工作。如下：

1. CPU **首次**读取未对齐地址的第一个内存块，读取 0-3 字节。并移除不需要的字节 0
2. CPU **再次**读取未对齐地址的第二个内存块，读取 4-7 字节。并移除不需要的字节 5、6、7 字节
3. 合并 1-4 字节的数据
4. 合并后放入寄存器

从上述流程可得出，不做 “内存对齐” 是一件有点 "麻烦" 的事。因为它会增加许多耗费时间的动作

而假设做了内存对齐，从 Index 0 开始读取 4 个字节，只需要读取一次，也不需要额外的运算。这显然高效很多，是标准的**空间换时间**做法

### 默认系数

在不同平台上的编译器都有自己默认的 “对齐系数”，可通过预编译命令 `#pragma pack(n)` 进行变更，n 就是代指 “对齐系数”。一般来讲，我们常用的平台的系数如下：

- 32 位：4
- 64 位：8

另外要注意，不同硬件平台占用的大小和对齐值都可能是不一样的。因此本文的值不是唯一的，调试的时候需按本机的实际情况考虑

### 成员对齐

```go
func main() {
	fmt.Printf("bool align: %d\n", unsafe.Alignof(bool(true)))
	fmt.Printf("int32 align: %d\n", unsafe.Alignof(int32(0)))
	fmt.Printf("int8 align: %d\n", unsafe.Alignof(int8(0)))
	fmt.Printf("int64 align: %d\n", unsafe.Alignof(int64(0)))
	fmt.Printf("byte align: %d\n", unsafe.Alignof(byte(0)))
	fmt.Printf("string align: %d\n", unsafe.Alignof("EDDYCJY"))
	fmt.Printf("map align: %d\n", unsafe.Alignof(map[string]string{}))
}
```

输出结果：

```
bool align: 1
int32 align: 4
int8 align: 1
int64 align: 8
byte align: 1
string align: 8
map align: 8
```

在 Go 中可以调用 `unsafe.Alignof` 来返回相应类型的对齐系数。通过观察输出结果，可得知基本都是 `2^n`，最大也不会超过 8。这是因为我手提（64 位）编译器默认对齐系数是 8，因此最大值不会超过这个数

### 整体对齐

在上小节中，提到了结构体中的成员变量要做字节对齐。那么想当然身为最终结果的结构体，也是需要做字节对齐的

### 对齐规则

- 结构体的成员变量，第一个成员变量的偏移量为 0。往后的每个成员变量的对齐值必须为**编译器默认对齐长度**（`#pragma pack(n)`）或**当前成员变量类型的长度**（`unsafe.Sizeof`），取**最小值作为当前类型的对齐值**。其偏移量必须为对齐值的整数倍
- 结构体本身，对齐值必须为**编译器默认对齐长度**（`#pragma pack(n)`）或**结构体的所有成员变量类型中的最大长度**，取**最大数的最小整数倍**作为对齐值
- 结合以上两点，可得知若**编译器默认对齐长度**（`#pragma pack(n)`）超过结构体内成员变量的类型最大长度时，默认对齐长度是没有任何意义的

## 分析流程

接下来我们一起分析一下，“它” 到底经历了些什么，影响了 “预期” 结果

| 成员变量   | 类型  | 偏移量 | 自身占用 |
| ---------- | ----- | ------ | -------- |
| a          | bool  | 0      | 1        |
| 字节对齐   | 无    | 1      | 3        |
| b          | int32 | 4      | 4        |
| c          | int8  | 8      | 1        |
| 字节对齐   | 无    | 9      | 7        |
| d          | int64 | 16     | 8        |
| e          | byte  | 24     | 1        |
| 字节对齐   | 无    | 25     | 7        |
| 总占用大小 | -     | -      | 32       |

### 成员对齐

- 第一个成员 a
  - 类型为 bool
  - 大小/对齐值为 1 字节
  - 初始地址，偏移量为 0。占用了第 1 位
- 第二个成员 b
  - 类型为 int32
  - 大小/对齐值为 4 字节
  - 根据规则 1，其偏移量必须为 4 的整数倍。确定偏移量为 4，因此 2-4 位为 Padding。而当前数值从第 5 位开始填充，到第 8 位。如下：axxx|bbbb
- 第三个成员 c
  - 类型为 int8
  - 大小/对齐值为 1 字节
  - 根据规则 1，其偏移量必须为 1 的整数倍。当前偏移量为 8。不需要额外对齐，填充 1 个字节到第 9 位。如下：axxx|bbbb|c...
- 第四个成员 d
  - 类型为 int64
  - 大小/对齐值为 8 字节
  - 根据规则 1，其偏移量必须为 8 的整数倍。确定偏移量为 16，因此 9-16 位为 Padding。而当前数值从第 17 位开始写入，到第 24 位。如下：axxx|bbbb|cxxx|xxxx|dddd|dddd
- 第五个成员 e
  - 类型为 byte
  - 大小/对齐值为 1 字节
  - 根据规则 1，其偏移量必须为 1 的整数倍。当前偏移量为 24。不需要额外对齐，填充 1 个字节到第 25 位。如下：axxx|bbbb|cxxx|xxxx|dddd|dddd|e...

### 整体对齐

在每个成员变量进行对齐后，根据规则 2，整个结构体本身也要进行字节对齐，因为可发现它可能并不是 `2^n`，不是偶数倍。显然不符合对齐的规则

根据规则 2，可得出对齐值为 8。现在的偏移量为 25，不是 8 的整倍数。因此确定偏移量为 32。对结构体进行对齐

### 结果

Part1 内存布局：axxx|bbbb|cxxx|xxxx|dddd|dddd|exxx|xxxx

### 小结

通过本节的分析，可得知先前的 “推算” 为什么错误？

是因为实际内存管理并非 “一个萝卜一个坑” 的思想。而是一块一块。通过空间换时间（效率）的思想来完成这块读取、写入。另外也需要兼顾不同平台的内存操作情况

## 巧妙的结构体

在上一小节，可得知根据成员变量的类型不同，其结构体的内存会产生对齐等动作。那假设字段顺序不同，会不会有什么变化呢？我们一起来试试吧 :-)

```go
type Part1 struct {
	a bool
	b int32
	c int8
	d int64
	e byte
}

type Part2 struct {
	e byte
	c int8
	a bool
	b int32
	d int64
}

func main() {
	part1 := Part1{}
	part2 := Part2{}

	fmt.Printf("part1 size: %d, align: %d\n", unsafe.Sizeof(part1), unsafe.Alignof(part1))
	fmt.Printf("part2 size: %d, align: %d\n", unsafe.Sizeof(part2), unsafe.Alignof(part2))
}
```

输出结果：

```
part1 size: 32, align: 8
part2 size: 16, align: 8
```

通过结果可以惊喜的发现，只是 “简单” 对成员变量的字段顺序进行改变，就改变了结构体占用大小

接下来我们一起剖析一下 `Part2`，看看它的内部到底和上一位之间有什么区别，才导致了这样的结果？

### 分析流程

| 成员变量   | 类型  | 偏移量 | 自身占用 |
| ---------- | ----- | ------ | -------- |
| e          | byte  | 0      | 1        |
| c          | int8  | 1      | 1        |
| a          | bool  | 2      | 1        |
| 字节对齐   | 无    | 3      | 1        |
| b          | int32 | 4      | 4        |
| d          | int64 | 8      | 8        |
| 总占用大小 | -     | -      | 16       |

#### 成员对齐

- 第一个成员 e
  - 类型为 byte
  - 大小/对齐值为 1 字节
  - 初始地址，偏移量为 0。占用了第 1 位
- 第二个成员 c
  - 类型为 int8
  - 大小/对齐值为 1 字节
  - 根据规则 1，其偏移量必须为 1 的整数倍。当前偏移量为 2。不需要额外对齐
- 第三个成员 a
  - 类型为 bool
  - 大小/对齐值为 1 字节
  - 根据规则 1，其偏移量必须为 1 的整数倍。当前偏移量为 3。不需要额外对齐
- 第四个成员 b
  - 类型为 int32
  - 大小/对齐值为 4 字节
  - 根据规则 1，其偏移量必须为 4 的整数倍。确定偏移量为 4，因此第 3 位为 Padding。而当前数值从第 4 位开始填充，到第 8 位。如下：ecax|bbbb
- 第五个成员 d
  - 类型为 int64
  - 大小/对齐值为 8 字节
  - 根据规则 1，其偏移量必须为 8 的整数倍。当前偏移量为 8。不需要额外对齐，从 9-16 位填充 8 个字节。如下：ecax|bbbb|dddd|dddd

#### 整体对齐

符合规则 2，不需要额外对齐

#### 结果

Part2 内存布局：ecax|bbbb|dddd|dddd

## 总结

通过对比 `Part1` 和 `Part2` 的内存布局，你会发现两者有很大的不同。如下：

- Part1：axxx|bbbb|cxxx|xxxx|dddd|dddd|exxx|xxxx

- Part2：ecax|bbbb|dddd|dddd

仔细一看，`Part1` 存在许多 Padding。显然它占据了不少空间，那么 Padding 是怎么出现的呢？

通过本文的介绍，可得知是由于不同类型导致需要进行字节对齐，以此保证内存的访问边界

那么也不难理解，为什么**调整结构体内成员变量的字段顺序**就能达到缩小结构体占用大小的疑问了，是因为巧妙地减少了 Padding 的存在。让它们更 “紧凑” 了。这一点对于加深 Go 的内存布局印象和大对象的优化非常有帮

当然了，没什么特殊问题，你可以不关注这一块。但你要知道这块知识点 😄

## 参考

- [Data structure alignment](https://en.wikipedia.org/wiki/Data_structure_alignment)
- [Data alignment](https://www.ibm.com/developerworks/library/pa-dalign/)


================================================
FILE: content/posts/go/talk/2019-01-20-control-goroutine.md
================================================
---

title:      "来，控制一下 goroutine 的并发数量"
date:       2019-01-20 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://s2.ax1x.com/2020/02/27/3wnOsJ.jpg)

## 问题

```go
func main() {
	userCount := math.MaxInt64
	for i := 0; i < userCount; i++ {
		go func(i int) {
		    // 做一些各种各样的业务逻辑处理
			fmt.Printf("go func: %d\n", i)
			time.Sleep(time.Second)
		}(i)
	}
}
```

在这里，假设 `userCount` 是一个外部传入的参数（不可预测，有可能值非常大），有人会全部丢进去循环。想着全部都并发 goroutine 去同时做某一件事。觉得这样子会效率会更高，对不对！

那么，你觉得这里有没有什么问题？

## 噩梦般的开始

当然，在**特定场景下**，问题可大了。因为在本文被丢进去同时并发的可是一个极端值。我们可以一起观察下图的指标分析，看看情况有多 “崩溃”。下图是上述代码的表现：

### 输出结果

```
...
go func: 5839
go func: 5840
go func: 5841
go func: 5842
go func: 5915
go func: 5524
go func: 5916
go func: 8209
go func: 8264
signal: killed
```

如果你自己执行过代码，在 “输出结果” 上你会遇到如下问题：

- 系统资源占用率不断上涨
- 输出一定数量后：控制台就不再刷新输出最新的值了
- 信号量：signal: killed

### 系统负载

![image](https://s2.ax1x.com/2020/02/27/3wnxd1.jpg)

### CPU

![image](https://s2.ax1x.com/2020/02/27/3wuKW8.jpg)

短时间内系统负载暴增

### 虚拟内存

![image](https://s2.ax1x.com/2020/02/27/3wu1yQ.jpg)

短时间内占用的虚拟内存暴增

### top

```
PID    COMMAND      %CPU  TIME     #TH   #WQ  #PORT MEM    PURG   CMPRS  PGRP  PPID  STATE    BOOSTS
...
73414  test         100.2 01:59.50 9/1   0    18    6801M+ 0B     114G+  73403 73403 running  *0[1]
```

### 小结

如果仔细看过监控工具的示意图，就可以知道其实我间隔的执行了两次，能看到系统间的使用率幅度非常大。当进程被杀掉后，整体又恢复为正常值

在这里，我们回到主题，就是在**不控制并发的 goroutine 数量** 会发生什么问题？大致如下：

- CPU 使用率浮动上涨
- Memory 占用不断上涨。也可以看看 CMPRS，它表示进程的压缩数据的字节数。已经到达 114G+ 了
- 主进程崩溃（被杀掉了）

简单来说，“崩溃” 的原因就是对系统资源的占用过大。常见的比如：打开文件数（too many files open）、内存占用等等

### 危害

对该台服务器产生非常大的影响，影响自身及相关联的应用。很有可能导致不可用或响应缓慢，另外启动了复数 “失控” 的 goroutine，导致程序流转混乱

## 解决方案

在前面花了大量篇幅，渲染了在存在大量并发 goroutine 数量时，不控制的话会出现 “严重” 的问题，接下来一起思考下解决方案。如下：

1. 控制/限制 goroutine 同时并发运行的数量
2. 改变应用程序的逻辑写法（避免大规模的使用系统资源和等待）
3. ~~调整服务的硬件配置、最大打开数、内存等阈值~~

## 控制 goroutine 并发数量

接下来正式的开始解决这个问题，希望你认真阅读的同时加以思考，因为这个问题在实际项目中真的是太常见了！

问题已经抛出来了，你需要做的是**想想有什么办法**解决这个问题。建议你自行思考一下技术方案。再接着往下看 :-)

### 尝试 chan

```go
func main() {
	userCount := 10
	ch := make(chan bool, 2)
	for i := 0; i < userCount; i++ {
		ch <- true
		go Read(ch, i)
	}

	//time.Sleep(time.Second)
}

func Read(ch chan bool, i int) {
	fmt.Printf("go func: %d\n", i)
	<- ch
}
```

输出结果：

```
go func: 1
go func: 2
go func: 3
go func: 4
go func: 5
go func: 6
go func: 7
go func: 8
go func: 0
```

嗯，我们似乎很好的控制了 2 个 2 个的 “顺序” 执行多个 goroutine。但是，问题出现了。你仔细数一下输出结果，才 9 个值？

这明显就不对。原因出在当主协程结束时，子协程也是会被终止掉的。因此剩余的 goroutine 没来及把值输出，就被送上路了（不信你把 `time.Sleep` 打开看看，看看输出数量）

### 尝试 sync

```go
...
var wg = sync.WaitGroup{}

func main() {
	userCount := 10
	for i := 0; i < userCount; i++ {
		wg.Add(1)
		go Read(i)
	}

	wg.Wait()
}

func Read(i int) {
	defer wg.Done()
	fmt.Printf("go func: %d\n", i)
}
```

嗯，单纯的使用 `sync.WaitGroup` 也不行。没有控制到同时并发的 goroutine 数量（代指达不到本文所要求的目标）

#### 小结

单纯**简单**使用 channel 或 sync 都有明显缺陷，不行。我们再看看组件配合能不能实现

### 尝试 chan + sync

```go
...
var wg = sync.WaitGroup{}

func main() {
	userCount := 10
	ch := make(chan bool, 2)
	for i := 0; i < userCount; i++ {
		wg.Add(1)
		go Read(ch, i)
	}

	wg.Wait()
}

func Read(ch chan bool, i int) {
	defer wg.Done()

	ch <- true
	fmt.Printf("go func: %d, time: %d\n", i, time.Now().Unix())
	time.Sleep(time.Second)
	<-ch
}
```

输出结果：

```
go func: 9, time: 1547911938
go func: 1, time: 1547911938
go func: 6, time: 1547911939
go func: 7, time: 1547911939
go func: 8, time: 1547911940
go func: 0, time: 1547911940
go func: 3, time: 1547911941
go func: 2, time: 1547911941
go func: 4, time: 1547911942
go func: 5, time: 1547911942
```

从输出结果来看，确实实现了控制 goroutine 以 2 个 2 个的数量去执行我们的 “业务逻辑”，当然结果集也理所应当的是乱序输出

### 方案一：简单 Semaphore

在确立了简单使用 chan + sync 的方案是可行后，我们重新将流转逻辑封装为 [gsema](https://github.com/EDDYCJY/gsema)，主程序变成如下：

```go
import (
	"fmt"
	"time"

	"github.com/EDDYCJY/gsema"
)

var sema = gsema.NewSemaphore(3)

func main() {
	userCount := 10
	for i := 0; i < userCount; i++ {
		go Read(i)
	}

	sema.Wait()
}

func Read(i int) {
	defer sema.Done()
	sema.Add(1)

	fmt.Printf("go func: %d, time: %d\n", i, time.Now().Unix())
	time.Sleep(time.Second)
}
```

### 分析方案

在上述代码中，程序执行流程如下：

- 设置允许的并发数目为 3 个
- 循环 10 次，每次启动一个 goroutine 来执行任务
- 每一个 goroutine 在内部利用 `sema` 进行调控是否阻塞
- 按允许并发数逐渐释出 goroutine，最后结束任务

看上去人模人样，没什么严重问题。但却有一个 “大” 坑，认真看到第二点 “每次启动一个 goroutine” 这句话。这里**有点问题**，提前产生那么多的 goroutine 会不会有什么问题，接下来一起分析下利弊，如下：

#### 利

- 适合**量不大、复杂度低**的使用场景
  - 几百几千个、几十万个也是可以接受的（看具体业务场景）
  - 实际业务逻辑在运行前就已经被阻塞等待了（因为并发数受限），基本实际业务逻辑损耗的性能比 goroutine 本身大
  - goroutine 本身很轻便，仅损耗极少许的内存空间和调度。这种等待响应的情况都是躺好了，等待任务唤醒
- Semaphore 操作复杂度低且流转简单，容易控制

#### 弊

- 不适合**量很大、复杂度高**的使用场景
  - 有几百万、几千万个 goroutine 的话，就浪费了大量调度 goroutine 和内存空间。恰好你的服务器也接受不了的话
- Semaphore 操作复杂度提高，要管理更多的状态

### 小结

- 基于什么业务场景，就用什么方案去做事
- 有足够的时间，允许你去追求更优秀、极致的方案（用第三方库也行）

用哪种方案，我认为主要基于以上两点去思考，都是 OK 的。没有对错，只有当前业务场景能不能接受，这个预先启动的 goroutine 数量你的系统是否能够接受

当然了，常见/简单的 Go 应用采用这类技术方案，基本就能解决问题了。因为像本文第一节 “问题” 如此超巨大数量的情况，情况很少。其并不存在那些 “特殊性”。因此用这个方案基本 OK

## 灵活控制 goroutine 并发数量

小手一紧。隔壁老王发现了新的问题。“方案一” 中，在**输入输出一体**的情况下，在常见的业务场景中确实可以

但，这次新的业务场景比较特殊，要控制输入的数量，以此达到**改变允许并发运行 goroutine 的数量**。我们仔细想想，要做出如下改变：

- 输入/输出要抽离，才可以分别控制
- 输入/输出要可变，理所应当在 for-loop 中（可设置数值的地方）
- 允许改变 goroutine 并发数量，但它也必须有一个**最大值**（因为允许改变是相对）

### 方案二：灵活 chan + sync

```go
package main

import (
	"fmt"
	"sync"
	"time"
)

var wg sync.WaitGroup

func main() {
	userCount := 10
	ch := make(chan int, 5)
	for i := 0; i < userCount; i++ {
		wg.Add(1)
		go func() {
			defer wg.Done()
			for d := range ch {
				fmt.Printf("go func: %d, time: %d\n", d, time.Now().Unix())
				time.Sleep(time.Second * time.Duration(d))
			}
		}()
	}

	for i := 0; i < 10; i++ {
		ch <- 1
		ch <- 2
		//time.Sleep(time.Second)
	}

	close(ch)
	wg.Wait()
}
```

输出结果：

```
...
go func: 1, time: 1547950567
go func: 3, time: 1547950567
go func: 1, time: 1547950567
go func: 2, time: 1547950567
go func: 2, time: 1547950567
go func: 3, time: 1547950567
go func: 1, time: 1547950568
go func: 2, time: 1547950568
go func: 3, time: 1547950568
go func: 1, time: 1547950568
go func: 3, time: 1547950569
go func: 2, time: 1547950569
```

在 “方案二” 中，我们可以随时随地的根据新的业务需求，做如下事情：

- 变更 channel 的输入数量
- 能够根据特殊情况，变更 channel 的循环值
- 变更最大允许并发的 goroutine 数量

总的来说，就是可控空间都尽量放开了，是不是更加灵活了呢 :-)

### 方案三：第三方库

- [go-playground/pool](https://github.com/go-playground/pool)
- [nozzle/throttler](https://github.com/nozzle/throttler)
- [Jeffail/tunny](https://github.com/Jeffail/tunny)
- [panjf2000/ants](https://github.com/panjf2000/ants)

比较成熟的第三方库也不少，基本都是以生成和管理 goroutine 为目标的池工具。我简单列了几个，具体建议大家阅读下源码或者多找找，原理相似

## 总结

在本文的开头，我花了大力气（极端数量），告诉你**同时并发过多的 goroutine 数量会导致系统占用资源不断上涨。最终该服务崩盘的极端情况**。为的是希望你今后避免这种问题，给你留下深刻的印象

接下来我们以 “控制 goroutine 并发数量” 为主题，展开了一番分析。分别给出了三种方案。在我看来，各具优缺点，我建议你**挑选合适自身场景的技术方案**就可以了

因为，有不同类型的技术方案也能解决这个问题，千人千面。本文推荐的是较常见的解决方案，也欢迎大家在评论区继续补充 :-)


================================================
FILE: content/posts/go/talk/2019-02-17-for-loop-json-unmarshal.md
================================================
---

title:      "for-loop 与 json.Unmarshal 性能分析概要"
date:       2019-02-17 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

在项目中，常常会遇到循环交换赋值的数据处理场景，尤其是 RPC，数据交互格式要转为 Protobuf，赋值是无法避免的。一般会有如下几种做法：

- for
- for range
- json.Marshal/Unmarshal

这时候又面临 “选择困难症”，用哪个好？又想代码量少，又担心性能有没有影响啊...

为了弄清楚这个疑惑，接下来将分别编写三种使用场景。来简单看看它们的性能情况，看看谁更 “好”

## 功能代码

```go
...
type Person struct {
	Name   string `json:"name"`
	Age    int    `json:"age"`
	Avatar string `json:"avatar"`
	Type   string `json:"type"`
}

type AgainPerson struct {
	Name   string `json:"name"`
	Age    int    `json:"age"`
	Avatar string `json:"avatar"`
	Type   string `json:"type"`
}

const MAX = 10000

func InitPerson() []Person {
	var persons []Person
	for i := 0; i < MAX; i++ {
		persons = append(persons, Person{
			Name:   "EDDYCJY",
			Age:    i,
			Avatar: "https://github.com/EDDYCJY",
			Type:   "Person",
		})
	}

	return persons
}

func ForStruct(p []Person, count int) {
	for i := 0; i < count; i++ {
		_, _ = i, p[i]
	}
}

func ForRangeStruct(p []Person) {
	for i, v := range p {
		_, _ = i, v
	}
}

func JsonToStruct(data []byte, againPerson []AgainPerson) ([]AgainPerson, error) {
	err := json.Unmarshal(data, &againPerson)
	return againPerson, err
}

func JsonIteratorToStruct(data []byte, againPerson []AgainPerson) ([]AgainPerson, error) {
	var jsonIter = jsoniter.ConfigCompatibleWithStandardLibrary
	err := jsonIter.Unmarshal(data, &againPerson)
	return againPerson, err
}
```

## 测试代码

```go
...
func BenchmarkForStruct(b *testing.B) {
	person := InitPerson()
	count := len(person)
	b.ResetTimer()
	for i := 0; i < b.N; i++ {
		ForStruct(person, count)
	}
}

func BenchmarkForRangeStruct(b *testing.B) {
	person := InitPerson()

	b.ResetTimer()
	for i := 0; i < b.N; i++ {
		ForRangeStruct(person)
	}
}

func BenchmarkJsonToStruct(b *testing.B) {
	var (
		person = InitPerson()
		againPersons []AgainPerson
	)
	data, err := json.Marshal(person)
	if err != nil {
		b.Fatalf("json.Marshal err: %v", err)
	}

	b.ResetTimer()
	for i := 0; i < b.N; i++ {
		JsonToStruct(data, againPersons)
	}
}

func BenchmarkJsonIteratorToStruct(b *testing.B) {
	var (
		person = InitPerson()
		againPersons []AgainPerson
	)
	data, err := json.Marshal(person)
	if err != nil {
		b.Fatalf("json.Marshal err: %v", err)
	}

	b.ResetTimer()
	for i := 0; i < b.N; i++ {
		JsonIteratorToStruct(data, againPersons)
	}
}
```

## 测试结果

```
BenchmarkForStruct-4              	  500000	      3289 ns/op	       0 B/op	       0 allocs/op
BenchmarkForRangeStruct-4         	  200000	      9178 ns/op	       0 B/op	       0 allocs/op
BenchmarkJsonToStruct-4           	     100	  19173117 ns/op	 2618509 B/op	   40036 allocs/op
BenchmarkJsonIteratorToStruct-4   	     300	   4116491 ns/op	 3694017 B/op	   30047 allocs/op
```

从测试结果来看，性能排名为：for < for range < json-iterator < encoding/json。接下来我们看看是什么原因导致了这样子的排名？

## 性能对比

![image](https://s2.ax1x.com/2020/02/27/3wuywR.png)

### for-loop

在测试结果中，`for range` 在性能上相较 `for` 差。这是为什么呢？在这里我们可以参见 `for range` 的 [实现](https://github.com/gcc-mirror/gcc/blob/master/gcc/go/gofrontend/statements.cc)，伪实现如下：

```go
for_temp := range
len_temp := len(for_temp)
for index_temp = 0; index_temp < len_temp; index_temp++ {
    value_temp = for_temp[index_temp]
    index = index_temp
    value = value_temp
    original body
}
```

通过分析伪实现，可得知 `for range` 相较 `for` 多做了如下事项

#### Expression

```
RangeClause = [ ExpressionList "=" | IdentifierList ":=" ] "range" Expression .
```

在循环开始之前会对范围表达式进行求值，多做了 “解” 表达式的动作，得到了最终的范围值

#### Copy

```go
...
value_temp = for_temp[index_temp]
index = index_temp
value = value_temp
...
```

从伪实现上可以得出，`for range` 始终使用**值拷贝**的方式来生成循环变量。通俗来讲，就是在每次循环时，都会对循环变量重新分配

#### 小结

通过上述的分析，可得知其比 `for` 慢的原因是 `for range` 有额外的性能开销，主要为**值拷贝的动作**导致的性能下降。这是它慢的原因

那么其实在 `for range` 中，我们可以使用 `_` 和 `T[i]` 也能达到和 `for` 差不多的性能。但这可能不是 `for range` 的设计本意了

### json.Marshal/Unmarshal

#### encoding/json

json 互转是在三种方案中最慢的，这是为什么呢？

众所皆知，官方的 `encoding/json` 标准库，是通过大量反射来实现的。那么 “慢”，也是必然的。可参见下述代码：

```go
...
func newTypeEncoder(t reflect.Type, allowAddr bool) encoderFunc {
    ...
	switch t.Kind() {
	case reflect.Bool:
		return boolEncoder
	case reflect.Int, reflect.Int8, reflect.Int16, reflect.Int32, reflect.Int64:
		return intEncoder
	case reflect.Uint, reflect.Uint8, reflect.Uint16, reflect.Uint32, reflect.Uint64, reflect.Uintptr:
		return uintEncoder
	case reflect.Float32:
		return float32Encoder
	case reflect.Float64:
		return float64Encoder
	case reflect.String:
		return stringEncoder
	case reflect.Interface:
		return interfaceEncoder
	case reflect.Struct:
		return newStructEncoder(t)
	case reflect.Map:
		return newMapEncoder(t)
	case reflect.Slice:
		return newSliceEncoder(t)
	case reflect.Array:
		return newArrayEncoder(t)
	case reflect.Ptr:
		return newPtrEncoder(t)
	default:
		return unsupportedTypeEncoder
	}
}
```

既然官方的标准库存在一定的 “问题”，那么有没有其他解决方法呢？目前在社区里，大多为两类方案。如下：

- 预编译生成代码（提前确定类型），可以解决运行时的反射带来的性能开销。缺点是增加了预生成的步骤
- 优化序列化的逻辑，性能达到最大化

接下来的实验，我们用第二种方案的库来测试，看看有没有改变。另外也推荐大家了解如下项目：

- [json-iterator/go](https://github.com/json-iterator/go)
- [mailru/easyjson](https://github.com/mailru/easyjson)
- [pquerna/ffjson](https://github.com/pquerna/ffjson)

#### json-iterator/go

目前社区较常用的是 json-iterator/go，我们在测试代码中用到了它

它的用法与标准库 100% 兼容，并且性能有较大提升。我们一起粗略的看下是怎么做到的，如下：

##### reflect2

利用 [modern-go/reflect2](https://github.com/modern-go/reflect2) 减少运行时调度开销

```go
...
type StructDescriptor struct {
	Type   reflect2.Type
	Fields []*Binding
}

...
type Binding struct {
	levels    []int
	Field     reflect2.StructField
	FromNames []string
	ToNames   []string
	Encoder   ValEncoder
	Decoder   ValDecoder
}

type Extension interface {
	UpdateStructDescriptor(structDescriptor *StructDescriptor)
	CreateMapKeyDecoder(typ reflect2.Type) ValDecoder
	CreateMapKeyEncoder(typ reflect2.Type) ValEncoder
	CreateDecoder(typ reflect2.Type) ValDecoder
	CreateEncoder(typ reflect2.Type) ValEncoder
	DecorateDecoder(typ reflect2.Type, decoder ValDecoder) ValDecoder
	DecorateEncoder(typ reflect2.Type, encoder ValEncoder) ValEncoder
}
```

##### struct Encoder/Decoder Cache

类型为 struct 时，只需要反射一次 Name 和 Type，会缓存 struct Encoder 和 Decoder

```go
var typeDecoders = map[string]ValDecoder{}
var fieldDecoders = map[string]ValDecoder{}
var typeEncoders = map[string]ValEncoder{}
var fieldEncoders = map[string]ValEncoder{}
var extensions = []Extension{}

....

fieldNames := calcFieldNames(field.Name(), tagParts[0], tag)
fieldCacheKey := fmt.Sprintf("%s/%s", typ.String(), field.Name())
decoder := fieldDecoders[fieldCacheKey]
if decoder == nil {
	decoder = decoderOfType(ctx.append(field.Name()), field.Type())
}
encoder := fieldEncoders[fieldCacheKey]
if encoder == nil {
	encoder = encoderOfType(ctx.append(field.Name()), field.Type())
}
```

##### 文本解析优化

#### 小结

相较于官方标准库，第三方库 `json-iterator/go` 在运行时上做的更好。这是它快的原因

有个需要注意的点，在 Go1.10 后 `map` 类型与标准库的已经没有太大的性能差异。但是，例如 `struct` 类型等仍然有较大的性能提高

## 总结

在本文中，我们首先进行了性能测试，再分析了不同方案，得知为什么了快慢的原因。那么最终在选择方案时，可以根据不同的应用场景去抉择：

- 对性能开销有较高要求：选用 `for`，开销最小
- 中规中矩：选用 `for range`，大对象慎用
- 量小、占用小、数量可控：选用 `json.Marshal/Unmarshal` 的方案也可以。其**重复代码**少，但开销最大

在绝大多数场景中，使用哪种并没有太大的影响。但作为工程师你应当清楚其利弊。以上就是不同的方案**分析概要**，希望对你有所帮助 :)


================================================
FILE: content/posts/go/talk/2019-03-31-go-ins.md
================================================
---

title:      "简单围观一下有趣的 //go: 指令"
date:       2019-03-31 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](http://wx2.sinaimg.cn/large/006fVPCvly1g1m1bplu3mj30xc0m8myg.jpg)

## 前言

如果你平时有翻看源码的习惯，你肯定会发现。咦，怎么有的方法上面总是写着 `//go:`  这类指令呢。他们到底是干嘛用的？

今天我们一同揭开他们的面纱，我将简单给你介绍一下，它们都负责些什么

## go:linkname

```
//go:linkname localname importpath.name
```

该指令指示编译器使用 `importpath.name` 作为源代码中声明为 `localname` 的变量或函数的目标文件符号名称。但是由于这个伪指令，可以破坏类型系统和包模块化。因此只有引用了 unsafe 包才可以使用

简单来讲，就是 `importpath.name` 是 `localname` 的符号别名，编译器实际上会调用 `localname` 。但前提是使用了 `unsafe` 包才能使用

### 案例

#### time/time.go
```
...
func now() (sec int64, nsec int32, mono int64)
```

#### runtime/timestub.go
```
import _ "unsafe" // for go:linkname

//go:linkname time_now time.now
func time_now() (sec int64, nsec int32, mono int64) {
	sec, nsec = walltime()
	return sec, nsec, nanotime() - startNano
}
```

在这个案例中可以看到 `time.now`，它并没有具体的实现。如果你初看可能会懵逼。这时候建议你全局搜索一下源码，你就会发现其实现在 `runtime.time_now` 中

配合先前的用法解释，可得知在 runtime 包中，我们声明了 `time_now` 方法是 `time.now` 的符号别名。并且在文件头引入了 `unsafe` 达成前提条件

## go:noescape

```
//go:noescape
```

该指令指定下一个有声明但没有主体（意味着实现有可能不是 Go）的函数，不允许编译器对其做逃逸分析

一般情况下，该指令用于内存分配优化。因为编译器默认会进行逃逸分析，会通过规则判定一个变量是分配到堆上还是栈上。但凡事有意外，一些函数虽然逃逸分析其是存放到堆上。但是对于我们来说，它是特别的。我们就可以使用 `go:noescape` 指令强制要求编译器将其分配到函数栈上

### 案例

```
// memmove copies n bytes from "from" to "to".
// in memmove_*.s
//go:noescape
func memmove(to, from unsafe.Pointer, n uintptr)
```

我们观察一下这个案例，它满足了该指令的常见特性。如下：

- memmove_*.s：只有声明，没有主体。其主体是由底层汇编实现的
- memmove：函数功能，在栈上处理性能会更好

## go:nosplit

```
//go:nosplit
```

该指令指定文件中声明的下一个函数不得包含堆栈溢出检查。简单来讲，就是这个函数跳过堆栈溢出的检查


### 案例

```
//go:nosplit
func key32(p *uintptr) *uint32 {
	return (*uint32)(unsafe.Pointer(p))
}
```

## go:nowritebarrierrec

```
//go:nowritebarrierrec
```

该指令表示编译器遇到写屏障时就会产生一个错误，并且允许递归。也就是这个函数调用的其他函数如果有写屏障也会报错。简单来讲，就是针对写屏障的处理，防止其死循环

### 案例

```
//go:nowritebarrierrec
func gcFlushBgCredit(scanWork int64) {
    ...
}
```

## go:yeswritebarrierrec

```
//go:yeswritebarrierrec
```

该指令与 `go:nowritebarrierrec` 相对，在标注 `go:nowritebarrierrec` 指令的函数上，遇到写屏障会产生错误。而当编译器遇到 `go:yeswritebarrierrec` 指令时将会停止

### 案例

```
//go:yeswritebarrierrec
func gchelper() {
	...
}
```

## go:noinline

该指令表示该函数禁止进行内联

### 案例

```
//go:noinline
func unexportedPanicForTesting(b []byte, i int) byte {
	return b[i]
}
```

我们观察一下这个案例，是直接通过索引取值，逻辑比较简单。如果不加上 `go:noinline` 的话，就会出现编译器对其进行内联优化

显然，内联有好有坏。该指令就是提供这一特殊处理

## go:norace

```
//go:norace
```

该指令表示禁止进行竞态检测。而另外一种常见的形式就是在启动时执行 `go run -race`，能够检测应用程序中是否存在双向的数据竞争。非常有用

### 案例

```
//go:norace
func forkAndExecInChild(argv0 *byte, argv, envv []*byte, chroot, dir *byte, attr *ProcAttr, sys *SysProcAttr, pipe int) (pid int, err Errno) {
    ...
}
```

## go:notinheap

```
//go:notinheap
```

该指令常用于类型声明，它表示这个类型不允许从 GC 堆上进行申请内存。在运行时中常用其来做较低层次的内部结构，避免调度器和内存分配中的写屏障。能够提高性能

### 案例

```
// notInHeap is off-heap memory allocated by a lower-level allocator
// like sysAlloc or persistentAlloc.
//
// In general, it's better to use real types marked as go:notinheap,
// but this serves as a generic type for situations where that isn't
// possible (like in the allocators).
//
//go:notinheap
type notInHeap struct{}
```

## 总结

在本文我们简单介绍了一些常见的指令集，我建议仅供了解。一般我们是用不到的，因为你的瓶颈可能更多的在自身应用上

但是了解这一些，对你了解底层源码和运行机制会更有帮助。如果想再深入些，可阅读我给出的参考链接 ：）

## 参考

- [HACKING](https://github.com/golang/go/blob/master/src/runtime/HACKING.md)
- [Command compile](https://golang.org/cmd/compile/)


================================================
FILE: content/posts/go/talk/2019-05-20-stack-heap.md
================================================
---

title:      "我要在栈上。不，你应该在堆上"
date:       2019-05-20 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://s2.ax1x.com/2020/02/27/3wK39K.jpg)

我们在写代码的时候，有时候会想这个变量到底分配到哪里了？这时候可能会有人说，在栈上，在堆上。信我准没错...

但从结果上来讲你还是一知半解，这可不行，万一被人懵了呢。今天我们一起来深挖下 Go 在这块的奥妙，自己动手丰衣足食

## 问题

```go
type User struct {
	ID     int64
	Name   string
	Avatar string
}

func GetUserInfo() *User {
	return &User{ID: 13746731, Name: "EDDYCJY", Avatar: "https://avatars0.githubusercontent.com/u/13746731"}
}

func main() {
	_ = GetUserInfo()
}
```

开局就是一把问号，带着问题进行学习。请问 main 调用 `GetUserInfo` 后返回的 `&User{...}`。这个变量是分配到栈上了呢，还是分配到堆上了？

## 什么是堆/栈

在这里并不打算详细介绍堆栈，仅简单介绍本文所需的基础知识。如下：

- 堆（Heap）：一般来讲是人为手动进行管理，手动申请、分配、释放。一般所涉及的内存大小并不定，一般会存放较大的对象。另外其分配相对慢，涉及到的指令动作也相对多
- 栈（Stack）：由编译器进行管理，自动申请、分配、释放。一般不会太大，我们常见的函数参数（不同平台允许存放的数量不同），局部变量等等都会存放在栈上

今天我们介绍的 Go 语言，它的堆栈分配是通过 Compiler 进行分析，GC 去管理的，而对其的分析选择动作就是今天探讨的重点

## 什么是逃逸分析

在编译程序优化理论中，逃逸分析是一种确定指针动态范围的方法，简单来说就是分析在程序的哪些地方可以访问到该指针

通俗地讲，逃逸分析就是确定一个变量要放堆上还是栈上，规则如下：

1. 是否有在其他地方（非局部）被引用。只要**有可能**被引用了，那么它**一定**分配到堆上。否则分配到栈上
2. 即使没有被外部引用，但对象过大，无法存放在栈区上。依然有可能分配到堆上

对此你可以理解为，逃逸分析是编译器用于决定变量分配到堆上还是栈上的一种行为

## 在什么阶段确立逃逸

在编译阶段确立逃逸，注意并不是在运行时

## 为什么需要逃逸

这个问题我们可以反过来想，如果变量都分配到堆上了会出现什么事情？例如：

- 垃圾回收（GC）的压力不断增大
- 申请、分配、回收内存的系统开销增大（相对于栈）
- 动态分配产生一定量的内存碎片

其实总的来说，就是频繁申请、分配堆内存是有一定 “代价” 的。会影响应用程序运行的效率，间接影响到整体系统。因此 “按需分配” 最大限度的灵活利用资源，才是正确的治理之道。这就是为什么需要逃逸分析的原因，你觉得呢？

## 怎么确定是否逃逸

第一，通过编译器命令，就可以看到详细的逃逸分析过程。而指令集 `-gcflags` 用于将标识参数传递给 Go 编译器，涉及如下：

- `-m` 会打印出逃逸分析的优化策略，实际上最多总共可以用 4 个 `-m`，但是信息量较大，一般用 1 个就可以了

- `-l` 会禁用函数内联，在这里禁用掉 inline 能更好的观察逃逸情况，减少干扰

```
$ go build -gcflags '-m -l' main.go
```

第二，通过反编译命令查看

```
$ go tool compile -S main.go
```

注：可以通过 `go tool compile -help` 查看所有允许传递给编译器的标识参数

## 逃逸案例

### 案例一：指针

第一个案例是一开始抛出的问题，现在你再看看，想想，如下：

```go
type User struct {
	ID     int64
	Name   string
	Avatar string
}

func GetUserInfo() *User {
	return &User{ID: 13746731, Name: "EDDYCJY", Avatar: "https://avatars0.githubusercontent.com/u/13746731"}
}

func main() {
	_ = GetUserInfo()
}
```

执行命令观察一下，如下：

```
$ go build -gcflags '-m -l' main.go
# command-line-arguments
./main.go:10:54: &User literal escapes to heap
```

通过查看分析结果，可得知 `&User` 逃到了堆里，也就是分配到堆上了。这是不是有问题啊...再看看汇编代码确定一下，如下：

```
$ go tool compile -S main.go
"".GetUserInfo STEXT size=190 args=0x8 locals=0x18
	0x0000 00000 (main.go:9)	TEXT	"".GetUserInfo(SB), $24-8
	...
	0x0028 00040 (main.go:10)	MOVQ	AX, (SP)
	0x002c 00044 (main.go:10)	CALL	runtime.newobject(SB)
	0x0031 00049 (main.go:10)	PCDATA	$2, $1
	0x0031 00049 (main.go:10)	MOVQ	8(SP), AX
	0x0036 00054 (main.go:10)	MOVQ	$13746731, (AX)
	0x003d 00061 (main.go:10)	MOVQ	$7, 16(AX)
	0x0045 00069 (main.go:10)	PCDATA	$2, $-2
	0x0045 00069 (main.go:10)	PCDATA	$0, $-2
	0x0045 00069 (main.go:10)	CMPL	runtime.writeBarrier(SB), $0
	0x004c 00076 (main.go:10)	JNE	156
	0x004e 00078 (main.go:10)	LEAQ	go.string."EDDYCJY"(SB), CX
    ...
```

我们将目光集中到 CALL 指令，发现其执行了 `runtime.newobject` 方法，也就是确实是分配到了堆上。这是为什么呢？

#### 分析结果

这是因为 `GetUserInfo()` 返回的是指针对象，引用被返回到了方法之外了。因此编译器会把该对象分配到堆上，而不是栈上。否则方法结束之后，局部变量就被回收了，岂不是翻车。所以最终分配到堆上是理所当然的

#### 再想想

那你可能会想，那就是所有指针对象，都应该在堆上？并不。如下：

```go
func main() {
	str := new(string)
	*str = "EDDYCJY"
}
```

你想想这个对象会分配到哪里？如下：

```
$ go build -gcflags '-m -l' main.go
# command-line-arguments
./main.go:4:12: main new(string) does not escape
```

显然，该对象分配到栈上了。很核心的一点就是它有没有被作用域之外所引用，而这里作用域仍然保留在 `main` 中，因此它没有发生逃逸

### 案例二：未确定类型

```go
func main() {
	str := new(string)
	*str = "EDDYCJY"

	fmt.Println(str)
}
```

执行命令观察一下，如下：

```
$ go build -gcflags '-m -l' main.go
# command-line-arguments
./main.go:9:13: str escapes to heap
./main.go:6:12: new(string) escapes to heap
./main.go:9:13: main ... argument does not escape
```

通过查看分析结果，可得知 `str` 变量逃到了堆上，也就是该对象在堆上分配。但上个案例时它还在栈上，我们也就 `fmt` 输出了它而已。这...到底发生了什么事？

#### 分析结果

相对案例一，案例二只加了一行代码 `fmt.Println(str)`，问题肯定出在它身上。其原型：

```go
func Println(a ...interface{}) (n int, err error)
```

通过对其分析，可得知当形参为 `interface` 类型时，在编译阶段编译器无法确定其具体的类型。因此会产生逃逸，最终分配到堆上

如果你有兴趣追源码的话，可以看下内部的 `reflect.TypeOf(arg).Kind()` 语句，其会造成堆逃逸，而表象就是 `interface` 类型会导致该对象分配到堆上

### 案例三、泄露参数

```go
type User struct {
	ID     int64
	Name   string
	Avatar string
}

func GetUserInfo(u *User) *User {
	return u
}

func main() {
	_ = GetUserInfo(&User{ID: 13746731, Name: "EDDYCJY", Avatar: "https://avatars0.githubusercontent.com/u/13746731"})
}
```

执行命令观察一下，如下：

```
$ go build -gcflags '-m -l' main.go
# command-line-arguments
./main.go:9:18: leaking param: u to result ~r1 level=0
./main.go:14:63: main &User literal does not escape
```

我们注意到 `leaking param` 的表述，它说明了变量 `u` 是一个泄露参数。结合代码可得知其传给 `GetUserInfo` 方法后，没有做任何引用之类的涉及变量的动作，直接就把这个变量返回出去了。因此这个变量实际上并没有逃逸，它的作用域还在 `main()` 之中，所以分配在栈上

#### 再想想

那你再想想怎么样才能让它分配到堆上？结合案例一，举一反三。修改如下：

```go
type User struct {
	ID     int64
	Name   string
	Avatar string
}

func GetUserInfo(u User) *User {
	return &u
}

func main() {
	_ = GetUserInfo(User{ID: 13746731, Name: "EDDYCJY", Avatar: "https://avatars0.githubusercontent.com/u/13746731"})
}
```

执行命令观察一下，如下：

```
$ go build -gcflags '-m -l' main.go
# command-line-arguments
./main.go:10:9: &u escapes to heap
./main.go:9:18: moved to heap: u
```

只要一小改，它就考虑会被外部所引用，因此妥妥的分配到堆上了

## 总结

在本文我给你介绍了逃逸分析的概念和规则，并列举了一些例子加深理解。但实际肯定远远不止这些案例，你需要做到的是掌握方法，遇到再看就好了。除此之外你还需要注意：

- 静态分配到栈上，性能一定比动态分配到堆上好
- 底层分配到堆，还是栈。实际上对你来说是透明的，不需要过度关心
- 每个 Go 版本的逃逸分析都会有所不同（会改变，会优化）
- 直接通过 `go build -gcflags '-m -l'` 就可以看到逃逸分析的过程和结果
- 到处都用指针传递并不一定是最好的，要用对

之前就有想过要不要写 “逃逸分析” 相关的文章，直到最近看到在夜读里有人问，还是有写的必要。对于这块的知识点。我的建议是适当了解，但没必要硬记。靠基础知识点加命令调试观察就好了。像是曹大之前讲的 “你琢磨半天逃逸分析，一压测，瓶颈在锁上”，完全没必要过度在意...

## 参考

- [Golang escape analysis](http://www.agardner.me/golang/garbage/collection/gc/escape/analysis/2015/10/18/go-escape-analysis.html)
- [FAQ](https://golang.org/doc/faq#stack_or_heap)
- [逃逸分析](https://zh.wikipedia.org/wiki/%E9%80%83%E9%80%B8%E5%88%86%E6%9E%90)


================================================
FILE: content/posts/go/talk/2019-06-16-defer-loss.md
================================================
---

title:      "Go1.12 defer 会有性能损耗，尽量不要用？"
date:       2019-06-16 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://s2.ax1x.com/2020/02/27/3wuUYV.jpg)

上个月在 @polaris @轩脉刃 的全栈技术群里看到一个小伙伴问 **“说 defer 在栈退出时执行，会有性能损耗，尽量不要用，这个怎么解？”**。

恰好前段时间写了一篇 [《深入理解 Go defer》](https://segmentfault.com/a/1190000019303572) 去详细剖析 `defer` 关键字。那么这一次简单结合前文对这个问题进行探讨一波，希望对你有所帮助，但在此之前希望你花几分钟，自己思考一下答案，再继续往下看。

## 测试

```go
func DoDefer(key, value string) {
    defer func(key, value string) {
        _ = key + value
    }(key, value)
}

func DoNotDefer(key, value string) {
    _ = key + value
}
```

基准测试：

```go
func BenchmarkDoDefer(b *testing.B) {
    for i := 0; i < b.N; i++ {
        DoDefer("煎鱼", "https://github.com/EDDYCJY/blog")
    }
}

func BenchmarkDoNotDefer(b *testing.B) {
    for i := 0; i < b.N; i++ {
        DoNotDefer("煎鱼", "https://github.com/EDDYCJY/blog")
    }
}
```

输出结果：

```
$ go test -bench=. -benchmem -run=none
goos: darwin
goarch: amd64
pkg: github.com/EDDYCJY/awesomeDefer
BenchmarkDoDefer-4          20000000            91.4 ns/op        48 B/op          1 allocs/op
BenchmarkDoNotDefer-4       30000000            41.6 ns/op        48 B/op          1 allocs/op
PASS
ok      github.com/EDDYCJY/awesomeDefer 3.234s
```

从结果上来，使用 `defer` 后的函数开销确实比没使用高了不少，这损耗用到哪里去了呢？

## 想一下

```
$ go tool compile -S main.go
"".main STEXT size=163 args=0x0 locals=0x40
    ...
    0x0059 00089 (main.go:6)    MOVQ    AX, 16(SP)
    0x005e 00094 (main.go:6)    MOVQ    $1, 24(SP)
    0x0067 00103 (main.go:6)    MOVQ    $1, 32(SP)
    0x0070 00112 (main.go:6)    CALL    runtime.deferproc(SB)
    0x0075 00117 (main.go:6)    TESTL    AX, AX
    0x0077 00119 (main.go:6)    JNE    137
    0x0079 00121 (main.go:7)    XCHGL    AX, AX
    0x007a 00122 (main.go:7)    CALL    runtime.deferreturn(SB)
    0x007f 00127 (main.go:7)    MOVQ    56(SP), BP
    0x0084 00132 (main.go:7)    ADDQ    $64, SP
    0x0088 00136 (main.go:7)    RET
    0x0089 00137 (main.go:6)    XCHGL    AX, AX
    0x008a 00138 (main.go:6)    CALL    runtime.deferreturn(SB)
    0x008f 00143 (main.go:6)    MOVQ    56(SP), BP
    0x0094 00148 (main.go:6)    ADDQ    $64, SP
    0x0098 00152 (main.go:6)    RET
    ...
```

我们在前文提到 `defer` 关键字其实涉及了一系列的连锁调用，内部 `runtime` 函数的调用就至少多了三步，分别是 `runtime.deferproc` 一次和 `runtime.deferreturn` 两次。

而这还只是在运行时的显式动作，另外编译器做的事也不少，例如：

- 在 `deferproc` 阶段（注册延迟调用），还得获取/传入目标函数地址、函数参数等等。
- 在 `deferreturn` 阶段，需要在函数调用结尾处插入该方法的调用，同时若有被 `defer` 的函数，还需要使用 `runtime·jmpdefer` 进行跳转以便于后续调用。

这一些动作途中还要涉及最小单元 `_defer` 的获取/生成， `defer` 和 `recover` 链表的逻辑处理和消耗等动作。

## Q&A

最后讨论的时候有提到 **“问题指的是本来就是用来执行 close() 一些操作的，然后说尽量不能用，例子就把 defer db.close() 前面的 defer 删去了”** 这个疑问。

这是一个比较类似 “教科书” 式的说法，在一些入门教程中会潜移默化的告诉你在资源控制后加个 `defer` 延迟关闭一下。例如：

```go
resp, err := http.Get(...)
if err != nil {
    return err
}
defer resp.Body.Close()
```

但是一定得这么写吗？其实并不，很多人给出的理由都是 “怕你忘记” 这种说辞，这没有毛病。但需要认清场景，假设我的应用场景如下：

```go
resp, err := http.Get(...)
if err != nil {
    return err
}
defer resp.Body.Close()
// do something
time.Sleep(time.Second * 60)
```

嗯，一个请求当然没问题，流量、并发一下子大了呢，那可能就是个灾难了。你想想为什么？从常见的 `defer` + `close` 的使用组合来讲，用之前建议先看清楚应用场景，在保证无异常的情况下确保尽早关闭才是首选。如果只是小范围调用很快就返回的话，偷个懒直接一套组合拳出去也未尝不可。

## 结论

一个 `defer` 关键字实际上包含了不少的动作和处理，和你单纯调用一个函数一条指令是没法比的。而与对照物相比，它确确实实是有性能损耗，目前延迟调用的全部开销大约在 50ns，但 `defer` 所提供的作用远远大于此，你从全局来看，它的损耗非常小，并且官方还不断地在优化中。

因此，对于 “Go defer 会有性能损耗，尽量不能用？” 这个问题，我认为**该用就用，应该及时关闭就不要延迟，在 hot paths 用时一定要想清楚场景**。

## 补充

最后补充上柴大的回复：**“不是性能问题，defer 最大的功能是 Panic 后依然有效。如果没有 defer，Panic 后就会导致 unlock 丢失，从而导致死锁了”**，非常经典。


================================================
FILE: content/posts/go/talk/2019-06-29-talking-grpc.md
================================================
---

title:      "从实践到原理，带你参透 gRPC"
date:       2019-06-29 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://image.eddycjy.com/4a47a0db6e60853dedfcfdf08a5ca249.png)

gRPC 在 Go 语言中大放异彩，越来越多的小伙伴在使用，最近也在公司安利了一波，希望这一篇文章能带你一览 gRPC 的巧妙之处，本文篇幅比较长，请做好阅读准备。本文目录如下：

![image](https://image.eddycjy.com/156005c5baf40ff51a327f1c34f2975b.jpg)

## 简述

gRPC 是一个高性能、开源和通用的 RPC 框架，面向移动和 HTTP/2 设计。目前提供 C、Java 和 Go 语言版本，分别是：grpc, grpc-java, grpc-go. 其中 C 版本支持 C, C++, Node.js, Python, Ruby, Objective-C, PHP 和 C# 支持。

gRPC 基于 HTTP/2 标准设计，带来诸如双向流、流控、头部压缩、单 TCP 连接上的多复用请求等特性。这些特性使得其在移动设备上表现更好，更省电和节省空间占用。

## 调用模型

![image](https://image.eddycjy.com/10fb15c77258a991b0028080a64fb42d.png)

1、客户端（gRPC Stub）调用 A 方法，发起 RPC 调用。

2、对请求信息使用 Protobuf 进行对象序列化压缩（IDL）。

3、服务端（gRPC Server）接收到请求后，解码请求体，进行业务逻辑处理并返回。

4、对响应结果使用 Protobuf 进行对象序列化压缩（IDL）。

5、客户端接受到服务端响应，解码请求体。回调被调用的 A 方法，唤醒正在等待响应（阻塞）的客户端调用并返回响应结果。

## 调用方式

### 一、Unary RPC：一元 RPC

![image](https://image.eddycjy.com/09dd8c2662b96ce14928333f055c5580.png)

#### Server

```go
type SearchService struct{}

func (s *SearchService) Search(ctx context.Context, r *pb.SearchRequest) (*pb.SearchResponse, error) {
    return &pb.SearchResponse{Response: r.GetRequest() + " Server"}, nil
}

const PORT = "9001"

func main() {
    server := grpc.NewServer()
    pb.RegisterSearchServiceServer(server, &SearchService{})

    lis, err := net.Listen("tcp", ":"+PORT)
    ...

    server.Serve(lis)
}
```

- 创建 gRPC Server 对象，你可以理解为它是 Server 端的抽象对象。
- 将 SearchService（其包含需要被调用的服务端接口）注册到 gRPC Server。 的内部注册中心。这样可以在接受到请求时，通过内部的 “服务发现”，发现该服务端接口并转接进行逻辑处理。
- 创建 Listen，监听 TCP 端口。
- gRPC Server 开始 lis.Accept，直到 Stop 或 GracefulStop。

#### Client

```go
func main() {
    conn, err := grpc.Dial(":"+PORT, grpc.WithInsecure())
    ...
    defer conn.Close()

    client := pb.NewSearchServiceClient(conn)
    resp, err := client.Search(context.Background(), &pb.SearchRequest{
        Request: "gRPC",
    })
    ...
}
```

- 创建与给定目标（服务端）的连接句柄。
- 创建 SearchService 的客户端对象。
- 发送 RPC 请求，等待同步响应，得到回调后返回响应结果。

### 二、Server-side streaming RPC：服务端流式 RPC

![image](https://image.eddycjy.com/8266e4bfeda1bd42d8f9794eb4ea0a13.png)

#### Server

```go
func (s *StreamService) List(r *pb.StreamRequest, stream pb.StreamService_ListServer) error {
    for n := 0; n <= 6; n++ {
        stream.Send(&pb.StreamResponse{
            Pt: &pb.StreamPoint{
                ...
            },
        })
    }

    return nil
}
```

#### Client

```go
func printLists(client pb.StreamServiceClient, r *pb.StreamRequest) error {
    stream, err := client.List(context.Background(), r)
    ...

    for {
        resp, err := stream.Recv()
        if err == io.EOF {
            break
        }
        ...
    }

    return nil
}
```

### 三、Client-side streaming RPC：客户端流式 RPC

![image](https://image.eddycjy.com/f19c9085129709ee14d013be869df69b.png)

#### Server

```go
func (s *StreamService) Record(stream pb.StreamService_RecordServer) error {
    for {
        r, err := stream.Recv()
        if err == io.EOF {
            return stream.SendAndClose(&pb.StreamResponse{Pt: &pb.StreamPoint{...}})
        }
        ...

    }

    return nil
}
```

#### Client

```go
func printRecord(client pb.StreamServiceClient, r *pb.StreamRequest) error {
    stream, err := client.Record(context.Background())
    ...

    for n := 0; n < 6; n++ {
        stream.Send(r)
    }

    resp, err := stream.CloseAndRecv()
    ...

    return nil
}
```

### 四、Bidirectional streaming RPC：双向流式 RPC

![image](https://image.eddycjy.com/9eb9cd58b9ea5e04c890326b5c1f471f.png)

#### Server

```go
func (s *StreamService) Route(stream pb.StreamService_RouteServer) error {
    for {
        stream.Send(&pb.StreamResponse{...})
        r, err := stream.Recv()
        if err == io.EOF {
            return nil
        }
        ...
    }

    return nil
}
```

#### Client

```go
func printRoute(client pb.StreamServiceClient, r *pb.StreamRequest) error {
    stream, err := client.Route(context.Background())
    ...

    for n := 0; n <= 6; n++ {
        stream.Send(r)
        resp, err := stream.Recv()
        if err == io.EOF {
            break
        }
        ...
    }

    stream.CloseSend()

    return nil
}
```

## 客户端与服务端是如何交互的

在开始分析之前，我们要先 gRPC 的调用有一个初始印象。那么最简单的就是对 Client 端调用 Server 端进行抓包去剖析，看看整个过程中它都做了些什么事。如下图：

![image](https://image.eddycjy.com/8cda81fc7ad906927144235dda5fdf15.jpg)

- Magic
- SETTINGS
- HEADERS
- DATA
- SETTINGS
- WINDOW_UPDATE
- PING
- HEADERS
- DATA
- HEADERS
- WINDOW_UPDATE
- PING

我们略加整理发现共有十二个行为，是比较重要的。在开始分析之前，建议你自己先想一下，它们的作用都是什么？大胆猜测一下，带着疑问去学习效果更佳。

### 行为分析

#### Magic

![image](https://image.eddycjy.com/30e62fddc14c05988b44e7c02788e187.jpg)

Magic 帧的主要作用是建立 HTTP/2 请求的前言。在 HTTP/2 中，要求两端都要发送一个连接前言，作为对所使用协议的最终确认，并确定 HTTP/2 连接的初始设置，客户端和服务端各自发送不同的连接前言。

而上图中的 Magic 帧是客户端的前言之一，内容为 `PRI * HTTP/2.0\r\n\r\nSM\r\n\r\n`，以确定启用 HTTP/2 连接。

#### SETTINGS

![image](https://image.eddycjy.com/ae566253288191ce5d879e51dae1d8c3.jpg)

![image](https://image.eddycjy.com/62bf1edb36141f114521ec4bb4175579.jpg)

SETTINGS 帧的主要作用是设置这一个连接的参数，作用域是整个连接而并非单一的流。

而上图的 SETTINGS 帧都是空 SETTINGS 帧，图一是客户端连接的前言（Magic 和 SETTINGS 帧分别组成连接前言）。图二是服务端的。另外我们从图中可以看到多个 SETTINGS 帧，这是为什么呢？是因为发送完连接前言后，客户端和服务端还需要有一步互动确认的动作。对应的就是带有 ACK 标识 SETTINGS 帧。

#### HEADERS

![image](https://image.eddycjy.com/8df7b73a7820f4aef47864f2a6c5fccf.jpg)

HEADERS 帧的主要作用是存储和传播 HTTP 的标头信息。我们关注到 HEADERS 里有一些眼熟的信息，分别如下：

- method：POST
- scheme：http
- path：/proto.SearchService/Search
- authority：:10001
- content-type：application/grpc
- user-agent：grpc-go/1.20.0-dev

你会发现这些东西非常眼熟，其实都是 gRPC 的基础属性，实际上远远不止这些，只是设置了多少展示多少。例如像平时常见的 `grpc-timeout`、`grpc-encoding` 也是在这里设置的。

#### DATA

![image](https://image.eddycjy.com/9414a8f5b810972c3c9a0e2860c07532.jpg)

DATA 帧的主要作用是装填主体信息，是数据帧。而在上图中，可以很明显看到我们的请求参数 gRPC 存储在里面。只需要了解到这一点就可以了。

#### HEADERS, DATA, HEADERS

![image](https://image.eddycjy.com/edab7ba7e203cd7576d1200465194ea8.jpg)

在上图中 HEADERS 帧比较简单，就是告诉我们 HTTP 响应状态和响应的内容格式。

![imgae](https://image.eddycjy.com/db3a17f7bcac837ecc1fe2bc630a5473.jpg)

在上图中 DATA 帧主要承载了响应结果的数据集，图中的 gRPC Server 就是我们 RPC 方法的响应结果。

![image](https://image.eddycjy.com/85b6f89b41cae26786ac72365fff771b.jpg)

在上图中 HEADERS 帧主要承载了 gRPC 状态 和 gRPC 状态消息，图中的 `grpc-status` 和 `grpc-message` 就是我们的 gRPC 调用状态的结果。

### 其它步骤

#### WINDOW_UPDATE

主要作用是管理和流的窗口控制。通常情况下打开一个连接后，服务器和客户端会立即交换 SETTINGS 帧来确定流控制窗口的大小。默认情况下，该大小设置为约 65 KB，但可通过发出一个 WINDOW_UPDATE 帧为流控制设置不同的大小。

![image](https://image.eddycjy.com/a269962fe1424e1ca3e68c328b9fed61.jpg)

#### PING/PONG

主要作用是判断当前连接是否仍然可用，也常用于计算往返时间。其实也就是 PING/PONG，大家对此应该很熟。

### 小结

![image](https://image.eddycjy.com/ba6beb7ae28ef0a97d7a0a038feb5060.png)

- 在建立连接之前，客户端/服务端都会发送**连接前言**（Magic+SETTINGS），确立协议和配置项。
- 在传输数据时，是会涉及滑动窗口（WINDOW_UPDATE）等流控策略的。
- 传播 gRPC 附加信息时，是基于 HEADERS 帧进行传播和设置；而具体的请求/响应数据是存储的 DATA 帧中的。
- 请求/响应结果会分为 HTTP 和 gRPC 状态响应两种类型。
- 客户端发起 PING，服务端就会回应 PONG，反之亦可。

这块 gRPC 的基础使用，你可以看看我另外的 [《gRPC 入门系列》](https://github.com/EDDYCJY/blog#grpc%E7%B3%BB%E5%88%97%E7%9B%AE%E5%BD%95)，相信对你一定有帮助。

## 浅谈理解

### 服务端

![image](https://image.eddycjy.com/7134f8f5aced525d1c11d229063305e7.png)

为什么四行代码，就能够起一个 gRPC Server，内部做了什么逻辑。你有想过吗？接下来我们一步步剖析，看看里面到底是何方神圣。

### 一、初始化

```go
// grpc.NewServer()
func NewServer(opt ...ServerOption) *Server {
	opts := defaultServerOptions
	for _, o := range opt {
		o(&opts)
	}
	s := &Server{
		lis:    make(map[net.Listener]bool),
		opts:   opts,
		conns:  make(map[io.Closer]bool),
		m:      make(map[string]*service),
		quit:   make(chan struct{}),
		done:   make(chan struct{}),
		czData: new(channelzData),
	}
	s.cv = sync.NewCond(&s.mu)
	...

	return s
}
```

这块比较简单，主要是实例 grpc.Server 并进行初始化动作。涉及如下：

- lis：监听地址列表。
- opts：服务选项，这块包含 Credentials、Interceptor 以及一些基础配置。
- conns：客户端连接句柄列表。
- m：服务信息映射。
- quit：退出信号。
- done：完成信号。
- czData：用于存储 ClientConn，addrConn 和 Server 的 channelz 相关数据。
- cv：当优雅退出时，会等待这个信号量，直到所有 RPC 请求都处理并断开才会继续处理。

### 二、注册

```go
pb.RegisterSearchServiceServer(server, &SearchService{})
```

#### 步骤一：Service API interface

```go
// search.pb.go
type SearchServiceServer interface {
	Search(context.Context, *SearchRequest) (*SearchResponse, error)
}

func RegisterSearchServiceServer(s *grpc.Server, srv SearchServiceServer) {
	s.RegisterService(&_SearchService_serviceDesc, srv)
}
```

还记得我们平时编写的 Protobuf 吗？在生成出来的 `.pb.go` 文件中，会定义出 Service APIs interface 的具体实现约束。而我们在 gRPC Server 进行注册时，会传入应用 Service 的功能接口实现，此时生成的 `RegisterServer` 方法就会保证两者之间的一致性。

#### 步骤二：Service API IDL

你想乱传糊弄一下？不可能的，请乖乖定义与 Protobuf 一致的接口方法。但是那个 `&_SearchService_serviceDesc` 又有什么作用呢？代码如下：

```go
// search.pb.go
var _SearchService_serviceDesc = grpc.ServiceDesc{
	ServiceName: "proto.SearchService",
	HandlerType: (*SearchServiceServer)(nil),
	Methods: []grpc.MethodDesc{
		{
			MethodName: "Search",
			Handler:    _SearchService_Search_Handler,
		},
	},
	Streams:  []grpc.StreamDesc{},
	Metadata: "search.proto",
}
```

这看上去像服务的描述代码，用来向内部表述 “我” 都有什么。涉及如下:

- ServiceName：服务名称
- HandlerType：服务接口，用于检查用户提供的实现是否满足接口要求
- Methods：一元方法集，注意结构内的 `Handler` 方法，其对应最终的 RPC 处理方法，在执行 RPC 方法的阶段会使用。
- Streams：流式方法集
- Metadata：元数据，是一个描述数据属性的东西。在这里主要是描述 `SearchServiceServer` 服务

#### 步骤三：Register Service

```go
func (s *Server) register(sd *ServiceDesc, ss interface{}) {
    ...
	srv := &service{
		server: ss,
		md:     make(map[string]*MethodDesc),
		sd:     make(map[string]*StreamDesc),
		mdata:  sd.Metadata,
	}
	for i := range sd.Methods {
		d := &sd.Methods[i]
		srv.md[d.MethodName] = d
	}
	for i := range sd.Streams {
		...
	}
	s.m[sd.ServiceName] = srv
}
```

在最后一步中，我们会将先前的服务接口信息、服务描述信息给注册到内部 `service` 去，以便于后续实际调用的使用。涉及如下：

- server：服务的接口信息
- md：一元服务的 RPC 方法集
- sd：流式服务的 RPC 方法集
- mdata：metadata，元数据

#### 小结

在这一章节中，主要介绍的是 gRPC Server 在启动前的整理和注册行为，看上去很简单，但其实一切都是为了后续的实际运行的预先准备。因此我们整理一下思路，将其串联起来看看，如下：

![image](https://image.eddycjy.com/75c168b671d4ce827fca23907d85f114.png)

### 三、监听

接下来到了整个流程中，最重要也是大家最关注的监听/处理阶段，核心代码如下：

```go
func (s *Server) Serve(lis net.Listener) error {
	...
	var tempDelay time.Duration
	for {
		rawConn, err := lis.Accept()
		if err != nil {
			if ne, ok := err.(interface {
				Temporary() bool
			}); ok && ne.Temporary() {
				if tempDelay == 0 {
					tempDelay = 5 * time.Millisecond
				} else {
					tempDelay *= 2
				}
				if max := 1 * time.Second; tempDelay > max {
					tempDelay = max
				}
				...
				timer := time.NewTimer(tempDelay)
				select {
				case <-timer.C:
				case <-s.quit:
					timer.Stop()
					return nil
				}
				continue
			}
			...
			return err
		}
		tempDelay = 0

		s.serveWG.Add(1)
		go func() {
			s.handleRawConn(rawConn)
			s.serveWG.Done()
		}()
	}
}
```

Serve 会根据外部传入的 Listener 不同而调用不同的监听模式，这也是 `net.Listener` 的魅力，灵活性和扩展性会比较高。而在 gRPC Server 中最常用的就是 `TCPConn`，基于 TCP Listener 去做。接下来我们一起看看具体的处理逻辑，如下：

![image](https://image.eddycjy.com/7ae5e99a8c2f19cd25f44313293553aa.png)

- 循环处理连接，通过 `lis.Accept` 取出连接，如果队列中没有需处理的连接时，会形成阻塞等待。
- 若 `lis.Accept` 失败，则触发休眠机制，若为第一次失败那么休眠 5ms，否则翻倍，再次失败则不断翻倍直至上限休眠时间 1s，而休眠完毕后就会尝试去取下一个 “它”。
- 若 `lis.Accept` 成功，则重置休眠的时间计数和启动一个新的 goroutine 调用 `handleRawConn` 方法去执行/处理新的请求，也就是大家很喜欢说的 “每一个请求都是不同的 goroutine 在处理”。
- 在循环过程中，包含了 “退出” 服务的场景，主要是硬关闭和优雅重启服务两种情况。

## 客户端

![image](https://image.eddycjy.com/2484a7df36877a14689574eebda6dd7c.png)

### 一、创建拨号连接

```go
// grpc.Dial(":"+PORT, grpc.WithInsecure())
func DialContext(ctx context.Context, target string, opts ...DialOption) (conn *ClientConn, err error) {
	cc := &ClientConn{
		target:            target,
		csMgr:             &connectivityStateManager{},
		conns:             make(map[*addrConn]struct{}),
		dopts:             defaultDialOptions(),
		blockingpicker:    newPickerWrapper(),
		czData:            new(channelzData),
		firstResolveEvent: grpcsync.NewEvent(),
	}
	...
	chainUnaryClientInterceptors(cc)
	chainStreamClientInterceptors(cc)

	...
}
```

`grpc.Dial` 方法实际上是对于 `grpc.DialContext` 的封装，区别在于 `ctx` 是直接传入 `context.Background`。其主要功能是**创建**与给定目标的客户端连接，其承担了以下职责：

- 初始化 ClientConn
- 初始化（基于进程 LB）负载均衡配置
- 初始化 channelz
- 初始化重试规则和客户端一元/流式拦截器
- 初始化协议栈上的基础信息
- 相关 context 的超时控制
- 初始化并解析地址信息
- 创建与服务端之间的连接

#### 连没连

之前听到有的人说调用 `grpc.Dial` 后客户端就已经与服务端建立起了连接，但这对不对呢？我们先鸟瞰全貌，看看正在跑的 goroutine。如下：

![image](https://image.eddycjy.com/cf5793938b321b67b3b667655b375703.jpg)

我们可以有几个核心方法一直在等待/处理信号，通过分析底层源码可得知。涉及如下：

```go
func (ac *addrConn) connect()
func (ac *addrConn) resetTransport()
func (ac *addrConn) createTransport(addr resolver.Address, copts transport.ConnectOptions, connectDeadline time.Time)
func (ac *addrConn) getReadyTransport()
```

在这里主要分析 goroutine 提示的 `resetTransport` 方法，看看都做了啥。核心代码如下：

```go
func (ac *addrConn) resetTransport() {
	for i := 0; ; i++ {
		if ac.state == connectivity.Shutdown {
			return
		}
		...
		connectDeadline := time.Now().Add(dialDuration)
		ac.updateConnectivityState(connectivity.Connecting)
		newTr, addr, reconnect, err := ac.tryAllAddrs(addrs, connectDeadline)
		if err != nil {
			if ac.state == connectivity.Shutdown {
				return
			}
			ac.updateConnectivityState(connectivity.TransientFailure)
			timer := time.NewTimer(backoffFor)
			select {
			case <-timer.C:
				...
			}
			continue
		}

		if ac.state == connectivity.Shutdown {
			newTr.Close()
			return
		}
		...
		if !healthcheckManagingState {
			ac.updateConnectivityState(connectivity.Ready)
		}
		...

		if ac.state == connectivity.Shutdown {
			return
		}
		ac.updateConnectivityState(connectivity.TransientFailure)
	}
}
```

在该方法中会不断地去尝试创建连接，若成功则结束。否则不断地根据 `Backoff` 算法的重试机制去尝试创建连接，直到成功为止。从结论上来讲，单纯调用 `DialContext` 是异步建立连接的，也就是并不是马上生效，处于 `Connecting` 状态，而正式下要到达 `Ready` 状态才可用。

#### 真的连了吗

![image](https://image.eddycjy.com/eb935669c45405844c35aafbd5fe43d7.jpg)

在抓包工具上提示一个包都没有，那么这算真正连接了吗？我认为这是一个表述问题，我们应该尽可能的严谨。如果你真的想通过 `DialContext` 方法就打通与服务端的连接，则需要调用 `WithBlock` 方法，虽然会导致阻塞等待，但最终连接会到达 `Ready` 状态（握手成功）。如下图：

![image](https://image.eddycjy.com/e0e28452229af52e70f87dd03c3a30c2.jpg)

### 二、实例化 Service API

```go
type SearchServiceClient interface {
	Search(ctx context.Context, in *SearchRequest, opts ...grpc.CallOption) (*SearchResponse, error)
}

type searchServiceClient struct {
	cc *grpc.ClientConn
}

func NewSearchServiceClient(cc *grpc.ClientConn) SearchServiceClient {
	return &searchServiceClient{cc}
}
```

这块就是实例 Service API interface，比较简单。

### 三、调用

```go
// search.pb.go
func (c *searchServiceClient) Search(ctx context.Context, in *SearchRequest, opts ...grpc.CallOption) (*SearchResponse, error) {
	out := new(SearchResponse)
	err := c.cc.Invoke(ctx, "/proto.SearchService/Search", in, out, opts...)
	if err != nil {
		return nil, err
	}
	return out, nil
}
```

proto 生成的 RPC 方法更像是一个包装盒，把需要的东西放进去，而实际上调用的还是 `grpc.invoke` 方法。如下：

```go
func invoke(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, opts ...CallOption) error {
	cs, err := newClientStream(ctx, unaryStreamDesc, cc, method, opts...)
	if err != nil {
		return err
	}
	if err := cs.SendMsg(req); err != nil {
		return err
	}
	return cs.RecvMsg(reply)
}
```

通过概览，可以关注到三块调用。如下：

- newClientStream：获取传输层 Trasport 并组合封装到 ClientStream 中返回，在这块会涉及负载均衡、超时控制、 Encoding、 Stream 的动作，与服务端基本一致的行为。
- cs.SendMsg：发送 RPC 请求出去，但其并不承担等待响应的功能。
- cs.RecvMsg：阻塞等待接受到的 RPC 方法响应结果。

#### 连接

```go
// clientconn.go
func (cc *ClientConn) getTransport(ctx context.Context, failfast bool, method string) (transport.ClientTransport, func(balancer.DoneInfo), error) {
	t, done, err := cc.blockingpicker.pick(ctx, failfast, balancer.PickOptions{
		FullMethodName: method,
	})
	if err != nil {
		return nil, nil, toRPCErr(err)
	}
	return t, done, nil
}
```

在 `newClientStream` 方法中，我们通过 `getTransport` 方法获取了 Transport 层中抽象出来的 ClientTransport 和 ServerTransport，实际上就是获取一个连接给后续 RPC 调用传输使用。

### 四、关闭连接

```go
// conn.Close()
func (cc *ClientConn) Close() error {
	defer cc.cancel()
    ...
	cc.csMgr.updateState(connectivity.Shutdown)
    ...
	cc.blockingpicker.close()
	if rWrapper != nil {
		rWrapper.close()
	}
	if bWrapper != nil {
		bWrapper.close()
	}

	for ac := range conns {
		ac.tearDown(ErrClientConnClosing)
	}
	if channelz.IsOn() {
		...
		channelz.AddTraceEvent(cc.channelzID, ted)
		channelz.RemoveEntry(cc.channelzID)
	}
	return nil
}
```

该方法会取消 ClientConn 上下文，同时关闭所有底层传输。涉及如下：

- Context Cancel
- 清空并关闭客户端连接
- 清空并关闭解析器连接
- 清空并关闭负载均衡连接
- 添加跟踪引用
- 移除当前通道信息

## Q&A

### 1. gRPC Metadata 是通过什么传输？

![image](https://image.eddycjy.com/129e458698c4745a32d44582161b51d8.jpg)

### 2. 调用 grpc.Dial 会真正的去连接服务端吗？

会，但是是异步连接的，连接状态为正在连接。但如果你设置了 `grpc.WithBlock` 选项，就会阻塞等待（等待握手成功）。另外你需要注意，当未设置 `grpc.WithBlock` 时，ctx 超时控制对其无任何效果。

### 3. 调用 ClientConn 不 Close 会导致泄露吗？

会，除非你的客户端不是常驻进程，那么在应用结束时会被动地回收资源。但如果是常驻进程，你又真的忘记执行 `Close` 语句，会造成的泄露。如下图：

**3.1. 客户端**

![image](https://image.eddycjy.com/e25418821200a0f7c8f9f81b22d21691.jpg)

**3.2. 服务端**

![image](https://image.eddycjy.com/19ee203f0229aae4b91567bff25442e5.png)

**3.3. TCP**

![image](https://image.eddycjy.com/f0d0b070be593820651230120b0374be.jpg)

### 4. 不控制超时调用的话，会出现什么问题？

短时间内不会出现问题，但是会不断积蓄泄露，积蓄到最后当然就是服务无法提供响应了。如下图：

![image](https://image.eddycjy.com/853b031a43495200d111d6f5239398a3.jpg)

### 5. 为什么默认的拦截器不可以传多个？

```go
func chainUnaryClientInterceptors(cc *ClientConn) {
	interceptors := cc.dopts.chainUnaryInts
	if cc.dopts.unaryInt != nil {
		interceptors = append([]UnaryClientInterceptor{cc.dopts.unaryInt}, interceptors...)
	}
	var chainedInt UnaryClientInterceptor
	if len(interceptors) == 0 {
		chainedInt = nil
	} else if len(interceptors) == 1 {
		chainedInt = interceptors[0]
	} else {
		chainedInt = func(ctx context.Context, method string, req, reply interface{}, cc *ClientConn, invoker UnaryInvoker, opts ...CallOption) error {
			return interceptors[0](ctx, method, req, reply, cc, getChainUnaryInvoker(interceptors, 0, invoker), opts...)
		}
	}
	cc.dopts.unaryInt = chainedInt
}
```

当存在多个拦截器时，取的就是第一个拦截器。因此结论是允许传多个，但并没有用。

### 6. 真的需要用到多个拦截器的话，怎么办？

可以使用 [go-grpc-middleware](https://github.com/grpc-ecosystem/go-grpc-middleware) 提供的 `grpc.UnaryInterceptor` 和 `grpc.StreamInterceptor` 链式方法，方便快捷省心。

单单会用还不行，我们再深剖一下，看看它是怎么实现的。核心代码如下：

```go
func ChainUnaryClient(interceptors ...grpc.UnaryClientInterceptor) grpc.UnaryClientInterceptor {
	n := len(interceptors)
	if n > 1 {
		lastI := n - 1
		return func(ctx context.Context, method string, req, reply interface{}, cc *grpc.ClientConn, invoker grpc.UnaryInvoker, opts ...grpc.CallOption) error {
			var (
				chainHandler grpc.UnaryInvoker
				curI         int
			)

			chainHandler = func(currentCtx context.Context, currentMethod string, currentReq, currentRepl interface{}, currentConn *grpc.ClientConn, currentOpts ...grpc.CallOption) error {
				if curI == lastI {
					return invoker(currentCtx, currentMethod, currentReq, currentRepl, currentConn, currentOpts...)
				}
				curI++
				err := interceptors[curI](currentCtx, currentMethod, currentReq, currentRepl, currentConn, chainHandler, currentOpts...)
				curI--
				return err
			}

			return interceptors[0](ctx, method, req, reply, cc, chainHandler, opts...)
		}
	}
    ...
}
```

当拦截器数量大于 1 时，从 `interceptors[1]` 开始递归，每一个递归的拦截器 `interceptors[i]` 会不断地执行，最后才真正的去执行 `handler` 方法。同时也经常有人会问拦截器的执行顺序是什么，通过这段代码你得出结论了吗？

### 7. 频繁创建 ClientConn 有什么问题？

这个问题我们可以反向验证一下，假设不公用 ClientConn 看看会怎么样？如下:

```go
func BenchmarkSearch(b *testing.B) {
	for i := 0; i < b.N; i++ {
		conn, err := GetClientConn()
		if err != nil {
			b.Errorf("GetClientConn err: %v", err)
		}
		_, err = Search(context.Background(), conn)
		if err != nil {
			b.Errorf("Search err: %v", err)
		}
	}
}
```

输出结果：

```
    ... connection error: desc = "transport: Error while dialing dial tcp :10001: socket: too many open files"
    ... connection error: desc = "transport: Error while dialing dial tcp :10001: socket: too many open files"
    ... connection error: desc = "transport: Error while dialing dial tcp :10001: socket: too many open files"
    ... connection error: desc = "transport: Error while dialing dial tcp :10001: socket: too many open files"
FAIL
exit status 1
```

当你的应用场景是存在高频次同时生成/调用 ClientConn 时，可能会导致系统的文件句柄占用过多。这种情况下你可以变更应用程序生成/调用 ClientConn 的模式，又或是池化它，这块可以参考 [grpc-go-pool](github.com/processout/grpc-go-pool) 项目。

### 8. 客户端请求失败后会默认重试吗？

会不断地进行重试，直到上下文取消。而重试时间方面采用 backoff 算法作为的重连机制，默认的最大重试时间间隔是 120s。

### 9. 为什么要用 HTTP/2 作为传输协议？

许多客户端要通过 HTTP 代理来访问网络，gRPC 全部用 HTTP/2 实现，等到代理开始支持 HTTP/2 就能透明转发 gRPC 的数据。不光如此，负责负载均衡、访问控制等等的反向代理都能无缝兼容 gRPC，比起自己设计 wire protocol 的 Thrift，这样做科学不少。@ctiller @滕亦飞

### 10. 在 Kubernetes 中 gRPC 负载均衡有问题？

gRPC 的 RPC 协议是基于 HTTP/2 标准实现的，HTTP/2 的一大特性就是不需要像 HTTP/1.1 一样，每次发出请求都要重新建立一个新连接，而是会复用原有的连接。

所以这将导致 kube-proxy 只有在连接建立时才会做负载均衡，而在这之后的每一次 RPC 请求都会利用原本的连接，那么实际上后续的每一次的 RPC 请求都跑到了同一个地方。

注：使用 k8s service 做负载均衡的情况下

## 总结

- gRPC 基于 HTTP/2 + Protobuf。
- gRPC 有四种调用方式，分别是一元、服务端/客户端流式、双向流式。
- gRPC 的附加信息都会体现在 HEADERS 帧，数据在 DATA 帧上。
- Client 请求若使用 grpc.Dial 默认是异步建立连接，当时状态为 Connecting。
- Client 请求若需要同步则调用 WithBlock()，完成状态为 Ready。
- Server 监听是循环等待连接，若没有则休眠，最大休眠时间 1s；若接收到新请求则起一个新的 goroutine 去处理。
- grpc.ClientConn 不关闭连接，会导致 goroutine 和 Memory 等泄露。
- 任何内/外调用如果不加超时控制，会出现泄漏和客户端不断重试。
- 特定场景下，如果不对 grpc.ClientConn 加以调控，会影响调用。
- 拦截器如果不用 go-grpc-middleware 链式处理，会覆盖。
- 在选择 gRPC 的负载均衡模式时，需要谨慎。

## 参考

- http://doc.oschina.net/grpc
- https://github.com/grpc/grpc/blob/master/doc/PROTOCOL-HTTP2.md
- https://juejin.im/post/5b88a4f56fb9a01a0b31a67e
- https://www.ibm.com/developerworks/cn/web/wa-http2-under-the-hood/index.html
- https://github.com/grpc/grpc-go/issues/1953
- https://www.zhihu.com/question/52670041


================================================
FILE: content/posts/go/talk/2019-09-07-go1.13-defer.md
================================================
---

title:      "Go1.13 defer 的性能是如何提高的"
date:       2019-09-07 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

最近 Go1.13 终于发布了，其中一个值得关注的特性就是 **defer 在大部分的场景下性能提升了30%**，但是官方并没有具体写是怎么提升的，这让大家非常的疑惑。而我因为之前写过[《深入理解 Go defer》](https://book.eddycjy.com/golang/defer/defer.html) 和 [《Go defer 会有性能损耗，尽量不要用？》](https://book.eddycjy.com/golang/talk/defer-loss.html) 这类文章，因此我挺感兴趣它是做了什么改变才能得到这样子的结果，所以今天和大家一起探索其中奥妙。

## 一、测试

### Go1.12

```
$ go test -bench=. -benchmem -run=none
goos: darwin
goarch: amd64
pkg: github.com/EDDYCJY/awesomeDefer
BenchmarkDoDefer-4      	20000000	        91.4 ns/op	      48 B/op	       1 allocs/op
BenchmarkDoNotDefer-4   	30000000	        41.6 ns/op	      48 B/op	       1 allocs/op
PASS
ok  	github.com/EDDYCJY/awesomeDefer	3.234s
```

### Go1.13

```
$ go test -bench=. -benchmem -run=none
goos: darwin
goarch: amd64
pkg: github.com/EDDYCJY/awesomeDefer
BenchmarkDoDefer-4      	15986062	        74.7 ns/op	      48 B/op	       1 allocs/op
BenchmarkDoNotDefer-4   	29231842	        40.3 ns/op	      48 B/op	       1 allocs/op
PASS
ok  	github.com/EDDYCJY/awesomeDefer	3.444s
```

在开场，我先以不标准的测试基准验证了先前的测试用例，确确实实在这两个版本中，`defer` 的性能得到了提高，但是看上去似乎不是百分百提高 30 %。

## 二、看一下

### 之前（Go1.12）

```
    0x0070 00112 (main.go:6)    CALL    runtime.deferproc(SB)
    0x0075 00117 (main.go:6)    TESTL    AX, AX
    0x0077 00119 (main.go:6)    JNE    137
    0x0079 00121 (main.go:7)    XCHGL    AX, AX
    0x007a 00122 (main.go:7)    CALL    runtime.deferreturn(SB)
    0x007f 00127 (main.go:7)    MOVQ    56(SP), BP
```

### 现在（Go1.13）

```
	0x006e 00110 (main.go:4)	MOVQ	AX, (SP)
	0x0072 00114 (main.go:4)	CALL	runtime.deferprocStack(SB)
	0x0077 00119 (main.go:4)	TESTL	AX, AX
	0x0079 00121 (main.go:4)	JNE	139
	0x007b 00123 (main.go:7)	XCHGL	AX, AX
	0x007c 00124 (main.go:7)	CALL	runtime.deferreturn(SB)
	0x0081 00129 (main.go:7)	MOVQ	112(SP), BP
```

从汇编的角度来看，像是 `runtime.deferproc` 改成了 `runtime.deferprocStack` 调用，难道是做了什么优化，我们**抱着疑问**继续看下去。

## 三、观察源码

### _defer

```
type _defer struct {
	siz     int32
	siz     int32 // includes both arguments and results
	started bool
	heap    bool
	sp      uintptr // sp at time of defer
	pc      uintptr
	fn      *funcval
	...
```

相较于以前的版本，最小单元的 `_defer` 结构体主要是新增了 `heap` 字段，用于标识这个 `_defer` 是在堆上，还是在栈上进行分配，其余字段并没有明确变更，那我们可以把聚焦点放在 `defer` 的堆栈分配上了，看看是做了什么事。

### deferprocStack

```
func deferprocStack(d *_defer) {
	gp := getg()
	if gp.m.curg != gp {
		throw("defer on system stack")
	}
	
	d.started = false
	d.heap = false
	d.sp = getcallersp()
	d.pc = getcallerpc()

	*(*uintptr)(unsafe.Pointer(&d._panic)) = 0
	*(*uintptr)(unsafe.Pointer(&d.link)) = uintptr(unsafe.Pointer(gp._defer))
	*(*uintptr)(unsafe.Pointer(&gp._defer)) = uintptr(unsafe.Pointer(d))

	return0()
}
```

这一块代码挺常规的，主要是获取调用 `defer` 函数的函数栈指针、传入函数的参数具体地址以及PC（程序计数器），这块在前文 [《深入理解 Go defer》](https://book.eddycjy.com/golang/defer/defer.html) 有详细介绍过，这里就不再赘述了。

那这个 `deferprocStack` 特殊在哪呢，我们可以看到它把 `d.heap` 设置为了 `false`，也就是代表 `deferprocStack` 方法是针对将 `_defer` 分配在栈上的应用场景的。

### deferproc

那么问题来了，它又在哪里处理分配到堆上的应用场景呢？

```
func newdefer(siz int32) *_defer {
	...
	d.heap = true
	d.link = gp._defer
	gp._defer = d
	return d
}
```

那么 `newdefer` 是在哪里调用的呢，如下：

```
func deferproc(siz int32, fn *funcval) { // arguments of fn follow fn
	...
	sp := getcallersp()
	argp := uintptr(unsafe.Pointer(&fn)) + unsafe.Sizeof(fn)
	callerpc := getcallerpc()

	d := newdefer(siz)
	...
}
```

非常明确，先前的版本中调用的 `deferproc` 方法，现在被用于对应分配到堆上的场景了。

### 小结

- 第一点：可以确定的是 `deferproc` 并没有被去掉，而是流程被优化了。
- 第二点：编译器会根据应用场景去选择使用 `deferproc` 还是 `deferprocStack` 方法，他们分别是针对分配在堆上和栈上的使用场景。

## 四、编译器如何选择

### esc

```
// src/cmd/compile/internal/gc/esc.go
case ODEFER:
	if e.loopdepth == 1 { // top level
		n.Esc = EscNever // force stack allocation of defer record (see ssa.go)
		break
	}
```

### ssa

```
// src/cmd/compile/internal/gc/ssa.go
case ODEFER:
	d := callDefer
	if n.Esc == EscNever {
		d = callDeferStack
	}
    s.call(n.Left, d)
```

### 小结

这块结合来看，核心就是当 `e.loopdepth == 1` 时，会将逃逸分析结果 `n.Esc` 设置为 `EscNever`，也就是将 `_defer` 分配到栈上，那这个 `e.loopdepth` 到底又是何方神圣呢，我们再详细看看代码，如下：

```
// src/cmd/compile/internal/gc/esc.go
type NodeEscState struct {
	Curfn             *Node
	Flowsrc           []EscStep 
	Retval            Nodes    
	Loopdepth         int32  
	Level             Level
	Walkgen           uint32
	Maxextraloopdepth int32
}
```

这里重点查看 `Loopdepth` 字段，目前它共有三个值标识，分别是:

- -1：全局。
- 0：返回变量。
- 1：顶级函数，又或是内部函数的不断增长值。

这个读起来有点绕，结合我们上述 `e.loopdepth == 1` 的表述来看，也就是当 `defer func` 是顶级函数时，将会分配到栈上。但是若在  `defer func` 外层出现显式的迭代循环，又或是出现隐式迭代，将会分配到堆上。其实深层表示的还是迭代深度的意思，我们可以来证实一下刚刚说的方向，显式迭代的代码如下：

```
func main() {
	for p := 0; p < 10; p++ {
		defer func() {
			for i := 0; i < 20; i++ {
				log.Println("EDDYCJY")
			}
		}()
	}
}
```

查看汇编情况：

```
$ go tool compile -S main.go
"".main STEXT size=122 args=0x0 locals=0x20
	0x0000 00000 (main.go:15)	TEXT	"".main(SB), ABIInternal, $32-0
	...
	0x0048 00072 (main.go:17)	CALL	runtime.deferproc(SB)
	0x004d 00077 (main.go:17)	TESTL	AX, AX
	0x004f 00079 (main.go:17)	JNE	83
	0x0051 00081 (main.go:17)	JMP	33
	0x0053 00083 (main.go:17)	XCHGL	AX, AX
	0x0054 00084 (main.go:17)	CALL	runtime.deferreturn(SB)
	...
```

显然，最终 `defer` 调用的是 `runtime.deferproc` 方法，也就是分配到堆上了，没毛病。而隐式迭代的话，你可以借助 `goto` 语句去实现这个功能，再自己验证一遍，这里就不再赘述了。

## 总结

从分析的结果上来看，官方说明的 Go1.13 defer 性能提高 30%，主要来源于其延迟对象的堆栈分配规则的改变，措施是由编译器通过对 `defer` 的 `for-loop` 迭代深度进行分析，如果 `loopdepth` 为 1，则设置逃逸分析的结果，将分配到栈上，否则分配到堆上。

的确，我个人觉得对大部分的使用场景来讲，是优化了不少，也解决了一些人吐槽 `defer` 性能 “差” 的问题。另外，我想从 Go1.13 起，你也需要稍微了解一下它这块的机制，别随随便便就来个狂野版嵌套迭代 `defer`，可能没法效能最大化。

如果你还想了解更多细节，可以看看 `defer` 这块的的[提交内容](https://github.com/golang/go/commit/fff4f599fe1c21e411a99de5c9b3777d06ce0ce6)，官方的测试用例也包含在里面。


================================================
FILE: content/posts/go/talk/2019-09-24-why-vsz-large.md
================================================
---

title:      "Go 应用内存占用太多，让排查？（VSZ篇）"
date:       2019-09-24 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

前段时间，某同学说某服务的容器因为超出内存限制，不断地重启，问我们是不是有内存泄露，赶紧排查，然后解决掉，省的出问题。我们大为震惊，赶紧查看监控+报警系统和性能分析，发现应用指标压根就不高，不像有泄露的样子。

那么问题是出在哪里了呢，我们进入某个容器里查看了 `top` 的系统指标，结果如下：

```shell
PID       VSZ    RSS   ... COMMAND
67459     2007m  136m  ... ./eddycjy-server
```

从结果上来看，也没什么大开销的东西，主要就一个 Go 进程，一看，某同学就说 VSZ 那么高，而某云上的容器内存指标居然恰好和 VSZ 的值相接近，因此某同学就怀疑是不是 VSZ 所导致的，觉得存在一定的关联关系。

而从最终的结论上来讲，上述的表述是不全对的，那么在今天，本篇文章将**主要围绕 Go 进程的 VSZ 来进行剖析**，看看到底它为什么那么 "高"，而在正式开始分析前，第一节为前置的补充知识，大家可按顺序阅读。

## 基础知识

### 什么是 VSZ 

VSZ 是该进程所能使用的虚拟内存总大小，它包括进程可以访问的所有内存，其中包括了被换出的内存（Swap）、已分配但未使用的内存以及来自共享库的内存。

### 为什么要虚拟内存

在前面我们有了解到 VSZ 其实就是该进程的虚拟内存总大小，那**如果我们想了解 VSZ 的话，那我们得先了解 “为什么要虚拟内存？”**。

本质上来讲，在一个系统中的进程是与其他进程共享 CPU 和主存资源的，而在现代的操作系统中，多进程的使用非常的常见，那么如果太多的进程需要太多的内存，那么在没有虚拟内存的情况下，物理内存很可能会不够用，就会导致其中有些任务无法运行，更甚至会出现一些很奇怪的现象，例如 “某一个进程不小心写了另一个进程使用的内存”，就会造成内存破坏，因此虚拟内存是非常重要的一个媒介。

### 虚拟内存包含了什么

![image](https://image.eddycjy.com/3062dec8cd187490adadbdbcf50c17d4.jpg)

而虚拟内存，又分为内核虚拟内存和进程虚拟内存，每一个进程的虚拟内存都是独立的， 呈现如上图所示。

这里也补充说明一下，在内核虚拟内存中，是包含了内核中的代码和数据结构，而内核虚拟内存中的某些区域会被映射到所有进程共享的物理页面中去，因此你会看到 ”内核虚拟内存“ 中实际上是包含了 ”物理内存“ 的，它们两者存在映射关系。而在应用场景上来讲，每个进程也会去共享内核的代码和全局数据结构，因此就会被映射到所有进程的物理页面中去。

![image](https://image.eddycjy.com/3ba1352075ace855104f4bd57752a2ad.jpg)

### 虚拟内存的重要能力

为了更有效地管理内存并且减少出错，现代系统提供了一种对主存的抽象概念，也就是今天的主角，叫做虚拟内存（VM），虚拟内存是硬件异常、硬件地址翻译、主存、磁盘文件和内核软件交互的地方，它为每个进程提供了一个大的、一致的和私有的地址空间，虚拟内存提供了三个重要的能力：

1. 它将主存看成是一个存储在磁盘上的地址空间的高速缓存，在主存中只保存活动区域，并根据需要在磁盘和主存之间来回传送数据，通过这种方式，它高效地使用了主存。
2. 它为每个进程提供了一致的地址空间，从而简化了内存管理。
3. 它保护了每个进程的地址空间不被其他进程破坏。

### 小结

上面发散的可能比较多，简单来讲，对于本文我们重点关注这些知识点，如下：

- 虚拟内存它是有各式各样内存交互的地方，它包含的不仅仅是 "自己"，**而在本文中，我们只需要关注 VSZ，也就是进程虚拟内存，它包含了你的代码、数据、堆、栈段和共享库**。
- 虚拟内存作为内存保护的工具，能够保证进程之间的内存空间独立，不受其他进程的影响，因此每一个进程的 VSZ 大小都不一样，互不影响。
- 虚拟内存的存在，系统给各进程分配的内存之和是可以大于实际可用的物理内存的，因此你也会发现你进程的物理内存总是比虚拟内存低的多的多。



## 排查问题

在了解了基础知识后，我们正式开始排查问题，第一步我们先编写一个测试程序，看看没有什么业务逻辑的 Go 程序，它初始的 VSZ 是怎么样的。

### 测试

应用代码：

```go
func main() {
	r := gin.Default()
	r.GET("/ping", func(c *gin.Context) {
		c.JSON(200, gin.H{
			"message": "pong",
		})
	})
	r.Run(":8001")
}
```

查看进程情况：

```shell
$ ps aux 67459
USER      PID  %CPU %MEM      VSZ    RSS   ...
eddycjy 67459   0.0  0.0  4297048    960   ...
```

从结果上来看，VSZ 为 4297048K，也就是 4G 左右，咋一眼看过去还是挺吓人的，明明没有什么业务逻辑，但是为什么那么高呢，真是令人感到好奇。

### 确认有没有泄露

在未知的情况下，我们可以首先看下 `runtime.MemStats` 和 `pprof`，确定应用到底有没有泄露。不过我们这块是演示程序，什么业务逻辑都没有，因此可以确定和应用没有直接关系。

```
# runtime.MemStats
# Alloc = 1298568
# TotalAlloc = 1298568
# Sys = 71893240
# Lookups = 0
# Mallocs = 10013
# Frees = 834
# HeapAlloc = 1298568
# HeapSys = 66551808
# HeapIdle = 64012288
# HeapInuse = 2539520
# HeapReleased = 64012288
# HeapObjects = 9179
...
```

### Go FAQ

接着我第一反应是去翻了 Go FAQ（因为看到过，有印象），其问题为 "Why does my Go process use so much virtual memory?"，回答如下：

> The Go memory allocator reserves a large region of virtual memory as an arena for allocations. This virtual memory is local to the specific Go process; the reservation does not deprive other processes of memory.
>
> To find the amount of actual memory allocated to a Go process, use the Unix top command and consult the RES (Linux) or RSIZE (macOS) columns.

这个 FAQ 是在 2012 年 10 月 [提交](https://github.com/golang/go/commit/2100947d4a25dcf875be1941d0e3a409ea85051e) 的，这么多年了也没有更进一步的说明，再翻了 issues 和 forum，一些关闭掉的 issue 都指向了 FAQ，这显然无法满足我的求知欲，因此我继续往下探索，看看里面到底都摆了些什么。

### 查看内存映射

在上图中，我们有提到进程虚拟内存，主要包含了你的代码、数据、堆、栈段和共享库，那初步怀疑是不是进程做了什么内存映射，导致了大量的内存空间被保留呢，为了确定这一点，我们通过如下命令去排查：

```powershell
$ vmmap --wide 67459
...
==== Non-writable regions for process 67459
REGION TYPE                      START - END             [ VSIZE  RSDNT  DIRTY   SWAP] PRT/MAX SHRMOD PURGE    REGION DETAIL
__TEXT                 00000001065ff000-000000010667b000 [  496K   492K     0K     0K] r-x/rwx SM=COW          /bin/zsh
__LINKEDIT             0000000106687000-0000000106699000 [   72K    44K     0K     0K] r--/rwx SM=COW          /bin/zsh
MALLOC metadata        000000010669b000-000000010669c000 [    4K     4K     4K     0K] r--/rwx SM=COW          DefaultMallocZone_0x10669b000 zone structure
...
__TEXT                 00007fff76c31000-00007fff76c5f000 [  184K   168K     0K     0K] r-x/r-x SM=COW          /usr/lib/system/libxpc.dylib
__LINKEDIT             00007fffe7232000-00007ffff32cb000 [192.6M  17.4M     0K     0K] r--/r-- SM=COW          dyld shared cache combined __LINKEDIT
...        

==== Writable regions for process 67459
REGION TYPE                      START - END             [ VSIZE  RSDNT  DIRTY   SWAP] PRT/MAX SHRMOD PURGE    REGION DETAIL
__DATA                 000000010667b000-0000000106682000 [   28K    28K    28K     0K] rw-/rwx SM=COW          /bin/zsh
...   
__DATA                 0000000106716000-000000010671e000 [   32K    28K    28K     4K] rw-/rwx SM=COW          /usr/lib/zsh/5.3/zsh/zle.so
__DATA                 000000010671e000-000000010671f000 [    4K     4K     4K     0K] rw-/rwx SM=COW          /usr/lib/zsh/5.3/zsh/zle.so
__DATA                 0000000106745000-0000000106747000 [    8K     8K     8K     0K] rw-/rwx SM=COW          /usr/lib/zsh/5.3/zsh/complete.so
__DATA                 000000010675a000-000000010675b000 [    4K     4K     4K     0K] rw-
...
```

这块主要是利用 macOS 的 `vmmap` 命令去查看内存映射情况，这样就可以知道这个进程的内存映射情况，从输出分析来看，**这些关联共享库占用的空间并不大，导致 VSZ 过高的根本原因不在共享库和二进制文件上，但是并没有发现大量保留内存空间的行为，这是一个问题点**。



注：若是 Linux 系统，可使用 `cat /proc/PID/maps` 或 `cat /proc/PID/smaps` 查看。

### 查看系统调用

既然在内存映射中，我们没有明确的看到保留内存空间的行为，那我们接下来看看该进程的系统调用，确定一下它是否存在内存操作的行为，如下：

```
$ sudo dtruss -a ./awesomeProject
...
 4374/0x206a2:     15620       6      3 mprotect(0x1BC4000, 0x1000, 0x0)		 = 0 0
...
 4374/0x206a2:     15781       9      4 sysctl([CTL_HW, 3, 0, 0, 0, 0] (2), 0x7FFEEFBFFA64, 0x7FFEEFBFFA68, 0x0, 0x0)		 = 0 0
 4374/0x206a2:     15783       3      1 sysctl([CTL_HW, 7, 0, 0, 0, 0] (2), 0x7FFEEFBFFA64, 0x7FFEEFBFFA68, 0x0, 0x0)		 = 0 0
 4374/0x206a2:     15899       7      2 mmap(0x0, 0x40000, 0x3, 0x1002, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0x4000000 0
 4374/0x206a2:     15930       3      1 mmap(0xC000000000, 0x4000000, 0x0, 0x1002, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0xC000000000 0
 4374/0x206a2:     15934       4      2 mmap(0xC000000000, 0x4000000, 0x3, 0x1012, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0xC000000000 0
 4374/0x206a2:     15936       2      0 mmap(0x0, 0x2000000, 0x3, 0x1002, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0x59B7000 0
 4374/0x206a2:     15942       2      0 mmap(0x0, 0x210800, 0x3, 0x1002, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0x4040000 0
 4374/0x206a2:     15947       2      0 mmap(0x0, 0x10000, 0x3, 0x1002, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0x1BD0000 0
 4374/0x206a2:     15993       3      0 madvise(0xC000000000, 0x2000, 0x8)		 = 0 0
 4374/0x206a2:     16004       2      0 mmap(0x0, 0x10000, 0x3, 0x1002, 0xFFFFFFFFFFFFFFFF, 0x0)		 = 0x1BE0000 0
...
```

在这小节中，我们通过 macOS 的 `dtruss` 命令监听并查看了运行这个程序所进行的所有系统调用，发现了与内存管理有一定关系的方法如下：

- mmap：创建一个新的虚拟内存区域，但这里需要注意，**就是当系统调用 mmap 时，它只是从虚拟内存中申请了一段空间出来，并不会去分配和映射真实的物理内存，而当你访问这段空间的时候，才会在当前时间真正的去分配物理内存**。那么对应到我们实际应用的进程中，那就是 VSZ 的增长后，而该内存空间又未正式使用的话，物理内存是不会有增长的。
- madvise：提供有关使用内存的建议，例如：MADV_NORMAL、MADV_RANDOM、MADV_SEQUENTIAL、MADV_WILLNEED、MADV_DONTNEED 等等。
- mprotect：设置内存区域的保护情况，例如：PROT_NONE、PROT_READ、PROT_WRITE、PROT_EXEC、PROT_SEM、PROT_SAO、PROT_GROWSUP、PROT_GROWSDOWN 等等。
- sysctl：在内核运行时动态地修改内核的运行参数。

在此比较可疑的是 `mmap` 方法，它在 `dtruss` 的最终统计中一共调用了 10 余次，我们可以相信它在 Go Runtime 的时候进行了大量的虚拟内存申请，我们再接着往下看，看看到底是在什么阶段进行了虚拟内存空间的申请。



注：若是 Linux 系统，可使用 `strace` 命令。

### 查看 Go Runtime

#### 启动流程

通过上述的分析，我们可以知道在 Go 程序启动的时候 VSZ 就已经不低了，并且确定不是共享库等的原因，且程序在启动时系统调用确实存在 `mmap` 等方法的调用，那么我们可以充分怀疑 Go 在初始化阶段就保留了该内存空间。那我们第一步要做的就是查看一下 Go 的引导启动流程，看看是在哪里申请的，引导过程如下：

```
graph TD
A(rt0_darwin_amd64.s:8<br/>_rt0_amd64_darwin) -->|JMP| B(asm_amd64.s:15<br/>_rt0_amd64)
B --> |JMP|C(asm_amd64.s:87<br/>runtime-rt0_go)
C --> D(runtime1.go:60<br/>runtime-args)
D --> E(os_darwin.go:50<br/>runtime-osinit)
E --> F(proc.go:472<br/>runtime-schedinit)
F --> G(proc.go:3236<br/>runtime-newproc)
G --> H(proc.go:1170<br/>runtime-mstart)
H --> I(在新创建的 p 和 m 上运行 runtime-main)
```

- runtime-osinit：获取 CPU 核心数。
- runtime-schedinit：初始化程序运行环境（包括栈、内存分配器、垃圾回收、P等）。
- runtime-newproc：创建一个新的 G 和 绑定 runtime.main。
- runtime-mstart：启动线程 M。

注：来自@曹大的 《Go 程序的启动流程》和@全成的 《Go 程序是怎样跑起来的》，推荐大家阅读。

#### 初始化运行环境

显然，我们要研究的是 runtime 里的 `schedinit` 方法，如下：

```
func schedinit() {
	...
	stackinit()
	mallocinit()
	mcommoninit(_g_.m)
	cpuinit()       // must run before alginit
	alginit()       // maps must not be used before this call
	modulesinit()   // provides activeModules
	typelinksinit() // uses maps, activeModules
	itabsinit()     // uses activeModules

	msigsave(_g_.m)
	initSigmask = _g_.m.sigmask

	goargs()
	goenvs()
	parsedebugvars()
	gcinit()
  ...
}
```

从用途来看，非常明显， `mallocinit` 方法会进行内存分配器的初始化，我们继续往下看。

#### 初始化内存分配器

##### mallocinit

接下来我们正式的分析一下 `mallocinit` 方法，在引导流程中， `mallocinit` 主要承担 Go 程序的内存分配器的初始化动作，而今天主要是针对虚拟内存地址这块进行拆解，如下：

```
func mallocinit() {
	...
	if sys.PtrSize == 8 {
		for i := 0x7f; i >= 0; i-- {
			var p uintptr
			switch {
			case GOARCH == "arm64" && GOOS == "darwin":
				p = uintptr(i)<<40 | uintptrMask&(0x0013<<28)
			case GOARCH == "arm64":
				p = uintptr(i)<<40 | uintptrMask&(0x0040<<32)
			case GOOS == "aix":
				if i == 0 {
					continue
				}
				p = uintptr(i)<<40 | uintptrMask&(0xa0<<52)
			case raceenabled:
				...
			default:
				p = uintptr(i)<<40 | uintptrMask&(0x00c0<<32)
			}
			hint := (*arenaHint)(mheap_.arenaHintAlloc.alloc())
			hint.addr = p
			hint.next, mheap_.arenaHints = mheap_.arenaHints, hint
		}
	} else {
      ...
	}
}
```

- 判断当前是 64 位还是 32 位的系统。
- 从 0x7fc000000000~0x1c000000000 开始设置保留地址。
- 判断当前 `GOARCH`、`GOOS` 或是否开启了竞态检查，根据不同的情况申请不同大小的连续内存地址，而这里的 `p` 是即将要要申请的连续内存地址的开始地址。
- 保存刚刚计算的 arena 的信息到 `arenaHint` 中。

可能会有小伙伴问，为什么要判断是 32 位还是 64 位的系统，这是因为不同位数的虚拟内存的寻址范围是不同的，因此要进行区分，否则会出现高位的虚拟内存映射问题。而在申请保留空间时，我们会经常提到 `arenaHint` 结构体，它是 `arenaHints `链表里的一个节点，结构如下：

```
type arenaHint struct {
	addr uintptr
	down bool
	next *arenaHint
}
```

- addr：`arena` 的起始地址
- down：是否最后一个 `arena`
- next：下一个 `arenaHint` 的指针地址

那么这里疯狂提到的 `arena` 又是什么东西呢，这其实是 Go 的内存管理中的概念，Go Runtime 会把申请的虚拟内存分为三个大块，如下：

![image](https://image.eddycjy.com/c415cfea1db7a60b33d99084f9f32ad1.jpg)

- spans：记录 arena 区域页号和 mspan 的映射关系。
- bitmap：标识 arena 的使用情况，在功能上来讲，会用于标识 arena 的哪些空间地址已经保存了对象。
- arean：arean 其实就是 Go 的堆区，是由 mheap 进行管理的，它的 MaxMem 是 512GB-1。而在功能上来讲，Go 会在初始化的时候申请一段连续的虚拟内存空间地址到 arean 保留下来，在真正需要申请堆上的空间时再从 arean 中取出来处理，这时候就会转变为物理内存了。

在这里的话，你需要理解 arean 区域在 Go 内存里的作用就可以了。

##### mmap 

我们刚刚通过上述的分析，已经知道 `mallocinit` 的用途了，但是你可能还是会有疑惑，就是我们之前所看到的 `mmap` 系统调用，和它又有什么关系呢，怎么就关联到一起了，接下来我们先一起来看看更下层的代码，如下：

```
func sysAlloc(n uintptr, sysStat *uint64) unsafe.Pointer {
	p, err := mmap(nil, n, _PROT_READ|_PROT_WRITE, _MAP_ANON|_MAP_PRIVATE, -1, 0)
	...
	mSysStatInc(sysStat, n)
	return p
}

func sysReserve(v unsafe.Pointer, n uintptr) unsafe.Pointer {
	p, err := mmap(v, n, _PROT_NONE, _MAP_ANON|_MAP_PRIVATE, -1, 0)
	...
}

func sysMap(v unsafe.Pointer, n uintptr, sysStat *uint64) {
	...
	munmap(v, n)
	p, err := mmap(v, n, _PROT_READ|_PROT_WRITE, _MAP_ANON|_MAP_FIXED|_MAP_PRIVATE, -1, 0)
  ...
}
```

在 Go Runtime 中存在着一系列的系统级内存调用方法，本文涉及的主要如下：

- sysAlloc：从 OS 系统上申请清零后的内存空间，调用参数是 `_PROT_READ|_PROT_WRITE, _MAP_ANON|_MAP_PRIVATE`，得到的结果需进行内存对齐。
- sysReserve：从 OS 系统中保留内存的地址空间，这时候还没有分配物理内存，调用参数是 `_PROT_NONE, _MAP_ANON|_MAP_PRIVATE`，得到的结果需进行内存对齐。
- sysMap：通知 OS 系统我们要使用已经保留了的内存空间，调用参数是 `_PROT_READ|_PROT_WRITE, _MAP_ANON|_MAP_FIXED|_MAP_PRIVATE`。

看上去好像很有道理的样子，但是 `mallocinit` 方法在初始化时，到底是在哪里涉及了 `mmap` 方法呢，表面看不出来，如下：

```
for i := 0x7f; i >= 0; i-- {
	...
	hint := (*arenaHint)(mheap_.arenaHintAlloc.alloc())
	hint.addr = p
	hint.next, mheap_.arenaHints = mheap_.arenaHints, hint
}
```

实际上在调用 `mheap_.arenaHintAlloc.alloc()` 时，调用的是 `mheap`  下的 `sysAlloc` 方法，而 `sysAlloc` 又会与 `mmap` 方法产生调用关系，并且这个方法与常规的 `sysAlloc` 还不大一样，如下：

```
var mheap_ mheap
...
func (h *mheap) sysAlloc(n uintptr) (v unsafe.Pointer, size uintptr) {
	...
	for h.arenaHints != nil {
		hint := h.arenaHints
		p := hint.addr
		if hint.down {
			p -= n
		}
		if p+n < p {
			v = nil
		} else if arenaIndex(p+n-1) >= 1<<arenaBits {
			v = nil
		} else {
			v = sysReserve(unsafe.Pointer(p), n)
		}
		...
}
```

你可以惊喜的发现 `mheap.sysAlloc` 里其实有调用 `sysReserve` 方法，而 `sysReserve` 方法又正正是从 OS 系统中保留内存的地址空间的特定方法，是不是很惊喜，一切似乎都串起来了。

#### 小结

在本节中，我们先写了一个测试程序，然后根据非常规的排查思路进行了一步步的跟踪怀疑，整体流程如下：

- 通过 `top` 或 `ps` 等命令，查看进程运行情况，分析基础指标。
- 通过 `pprof` 或 `runtime.MemStats ` 等工具链查看应用运行情况，分析应用层面是否有泄露或者哪儿高。
- 通过 `vmmap` 命令，查看进程的内存映射情况，分析是不是进程虚拟空间内的某个区域比较高，例如：共享库等。
- 通过 `dtruss` 命令，查看程序的系统调用情况，分析可能出现的一些特殊行为，例如：在分析中我们发现  `mmap` 方法调用的比例是比较高的，那我们有充分的理由怀疑 Go 在启动时就进行了大量的内存空间保留。
- 通过上述的分析，确定可能是在哪个环节申请了那么多的内存空间后，再到 Go Runtime 中去做进一步的源码分析，因为源码面前，了无秘密，没必要靠猜。

从结论上而言，VSZ（进程虚拟内存大小）与共享库等没有太大的关系，主要与 Go Runtime 存在直接关联，也就是在前图中表示的运行时堆（malloc）。转换到 Go Runtime 里，就是在 `mallocinit`  这个内存分配器的初始化阶段里进行了一定量的虚拟空间的保留。

而保留虚拟内存空间时，受什么影响，又是一个哲学问题。从源码上来看，主要如下：

- 受不同的 OS 系统架构（GOARCH/GOOS）和位数（32/64 位）的影响。
- 受内存对齐的影响，计算回来的内存空间大小是需要经过对齐才会进行保留。

## 总结

我们通过一步步地分析，讲解了 Go 会在哪里，又会受什么因素，去调用了什么方法保留了那么多的虚拟内存空间，但是我们肯定会忧心进程虚拟内存（VSZ）高，会不会存在问题呢，我分析如下：

- VSZ 并不意味着你真正使用了那些物理内存，因此是不需要担心的。
- VSZ 并不会给 GC 带来压力，GC 管理的是进程实际使用的物理内存，而 VSZ 在你实际使用它之前，它并没有过多的代价。
- VSZ 基本都是不可访问的内存映射，也就是它并没有内存的访问权限（不允许读、写和执行）。

看到这里舒一口气，因为 Go VSZ 的高，并不会对我们产生什么非常实质性的问题，但是又仔细一想，为什么 Go 要申请那么多的虚拟内存呢，到底有啥用呢，考虑如下：Go 的设计是考虑到 `arena` 和  `bitmap` 的后续使用，先提早保留了整个内存地址空间。 然后随着 Go Runtime 和应用的逐步使用，肯定也会开始实际的申请和使用内存，这时候 `arena` 和 `bitmap` 的内存分配器就只需要将事先申请好的内存地址空间保留更改为实际可用的物理内存就好了，这样子可以极大的提高效能。

## 参考

- [曹大的 Go 程序的启动流程](http://xargin.com/go-bootstrap/)
- [全成的 Go 程序是怎样跑起来的](https://www.cnblogs.com/qcrao-2018/p/11124360.html)
- [推荐阅读 欧神的 go-under-the-hood](https://github.com/changkun/go-under-the-hood/blob/master/book/zh-cn/part2runtime/ch07alloc/readme.md)
- [High virtual memory allocation by golang](https://forum.golangbridge.org/t/high-virtual-memory-allocation-by-golang/6716)
- [GO MEMORY MANAGEMENT](https://povilasv.me/go-memory-management/)
- [GoBigVirtualSize](https://utcc.utoronto.ca/~cks/space/blog/programming/GoBigVirtualSize)
- [GoProgramMemoryUse](https://utcc.utoronto.ca/~cks/space/blog/programming/GoProgramMemoryUse)



================================================
FILE: content/posts/go/ternary-operator.md
================================================
---
title: "Go 凭什么不支持三元运算符？"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - go
  - 为什么
---

大家好，我是煎鱼。

这是一个很多其他语言工程师转 Go 语言的时间节点，这就难免不论一番比较。其中一个经典的运算上的就是 “三元运算符”：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/05766eebaf454d7fb91b60ab1c851cf4~tplv-k3u1fbpfcp-zoom-1.image)

为什么 Go 语言不支持三元运算符，Go 不支持三元运算符就是设计的不好，是历史在开倒车吗？

今天就由煎鱼来和大家一起摸索为什么。

三元运算符是什么
--------

三元运算符，在典型的数学意义上，或者从解析器的角度来看，是一个需要三个参数的运算符。而我们日常中，最常见的是二元运算符：

```
x + y
x / y
x * y
```

还有一元运算符：

```
-a
~b
!c

```

以及今天的男主角 “三元运算符”。在 C/C++ 等多种语言中，我们可以根据条件声明和初始化变量的习惯来选择性使用三元条件运算符：

```
int index = val > 0 ? val : -val
```

Go 使用三元运算符
----------

想在 Go 语言里也使用三元运算符时，发现居然没有...想要实现与上面相同的代码段的方式似乎只能：

```
var index int

if val > 0 {
    index = val
} else {
    index = -val
}
```

看上去十分的冗余，不够简洁。

为什么 Go 没有三元运算符
--------------

为什么 Go 没有 `?:` 操作符，没有的话，官方推荐的方式是怎么样的。

通过 Go FAQ 我们可以得知：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9ca7870161614747ae7decb88b4ce427~tplv-k3u1fbpfcp-zoom-1.image)

Go 官方就是推荐我们使用前面提到的方式来替代，并且明确了如下态度：

*   Go 中没有 `?:` 的原因是语言的设计者看到这个操作经常被用来创建难以理解的复杂表达式。
    
*   在替代方案上，if-else 形式虽然较长，但无疑是更清晰的。一门语言只需要一个条件控制流结构。
    

整体来讲，Go 语言的设计者是为了考虑**可读性**拒绝了实现三元运算符，"less is more." 也是标榜台词了。

社区争议
----

Go 语言的一些点与众不同，基本是大家皆知的。无论是 if err != nil，又或是本次的三元运算符，要大家用 if-else 替代：

```
if expr {
    n = trueVal
} else {
    n = falseVal
}
```

### 反对和同意

#### 反对

因此有社区小伙伴给出了反对，基本分为如下几类：

1.  认为 if-else 也有以类似情况能被滥用，设计者的理由不够充分，认为是 “借口”。
    
2.  认为三元运算符的 “丑陋” 问题，是开发者的编码问题，而不是语言问题。三元在各种语言中很常见，它们是正常的，Go 语言也应该要有。
    
3.  认为用 if-else 替代三元运算符也很麻烦，让开发者多读了 3-4 行和额外的缩进级别。
    

#### 同意

认可这个决策的也有不少，为此给出了大量的真实工程案例。

一般来讲，我们用三元运算符是希望这么用：

```
cond ? true_value : false_value
```

你可能见过这么用：

```
cond ? value_a + value_b : value_c * value_d
```

还见过这样：

```
(((cond_a ? val_one) : cond_b) ? val_two) : val_three

cond_a ? (val_one : (cond_b ? (val_two : val_three)))
```

还能嵌套三元运算符：

```
int a = cond_a ? val_one :
    cond_b ? val_two :
    cond_c ? val_three : val_four;
```

也能出现可读性更差的：

```
void rgb_to_lightness_(
  const double re, const double gr, const double bl, double &li)
{
  li=((re < gr) ? ((gr < bl) ? bl : gr) : ((re < bl) ? bl : re) +
                            (gr < re)
                          ? ((bl < gr) ? bl : gr)
                          : ((bl < re) ? bl : re)) / 2.0;
}
```

说白了就是真实的代码工程中，大家见到过大量三元运算符滥用的场景，纷纷给出了大量的难理解的例子，让大家困扰不堪。

总结
--

在这篇文章中，首先针对 “三元运算符” 做了基本的介绍。紧接着根据 Go 语言不支持三元的态度进行了说明，且面向社区的争议我们分为了正反方面的基本诠释。

实际上一个简单的 `?:` 既整洁又实用，但是没有很好又高效的办法方法可以防止丑陋的嵌套，也就是排除可读性的问题。

在真实的业务工程中，常常能看到一个三元运算符，**一开始只是很简单。后面嵌套越加越深，逻辑越写越复杂，从而带来了许多维护上的问题**。

给大家抛出如下问题：

*   你认为 Go 语言是否要有三元运算符呢？
    
*   如果要有，复杂嵌套的三元运算符又如何考虑呢？
    

**欢迎大家在评论区留言和交流 ：）**

## 鼓励


若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，学习 Go 语言可以看 [Go 学习地图和路线](https://github.com/eddycjy/go-developer-roadmap)，欢迎 Star 催更。

================================================
FILE: content/posts/go/throw.md
================================================
---
title: "Go 有哪些无法恢复的致命场景？"
date: 2021-12-31T12:55:26+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

有一次事故现场，在紧急恢复后，他正在排查代码，查了好一会。我回头一看，这错误提醒很明显就是致命错误，较好定位。

但此时，他竟然在查 panic-recover 是不是哪里漏了，我表示大受震惊...

今天就由煎鱼给大家分享一下错误类型有哪几种，又在什么场景下会触发。

## 错误类型

### error

第一种是 Go 中最标准的 error 错误，其真身是一个 interface{}。

如下：

```go
type error interface {
    Error() string
}
```

在日常工程中，我们只需要创建任意结构体，实现了 Error 方法，就可以认为是 error 错误类型。

如下：

```go
type errorString struct {
    s string
}

func (e *errorString) Error() string {
    return e.s
}
```

在外部调用标准库 API，一般如下：

```go
f, err := os.Open("filename.ext")
if err != nil {
    log.Fatal(err)
}
// do something with the open *File f
```

我们会约定最后一个参数为 error 类型，一般常见于第二个参数，可以有个约定俗成的习惯。

### panic

第二种是 Go 中的异常处理 panic，能够产生异常错误，结合 panic+recover 可以扭转程序的运行状态。

如下：

```go
package main

import "os"

func main() {
    panic("a problem")

    _, err := os.Create("/tmp/file")
    if err != nil {
        panic(err)
    }
}
```

输出结果：

```go
$ go run panic.go
panic: a problem
goroutine 1 [running]:
main.main()
    /.../panic.go:12 +0x47
...
exit status 2
```

如果没有使用 recover 作为捕获，就会导致程序中断。也因此经常被人误以为程序中断，就 100% 是 panic 导致的。

这是一个误区。

### throw

第三种是 Go 初学者经常踩坑，也不知道的错误类型，那就是致命错误 throw。

这个错误类型，在用户侧是没法主动调用的，均为 Go 底层自行调用的，像是大家常见的 map 并发读写，就是由此触发。

其源码如下：

```go
func throw(s string) {
	systemstack(func() {
		print("fatal error: ", s, "\n")
	})
	gp := getg()
	if gp.m.throwing == 0 {
		gp.m.throwing = 1
	}
	fatalthrow()
	*(*int)(nil) = 0 // not reached
}
```

根据上述程序，会获取当前 G 的实例，并设置其 M 的 throwing 状态为 1。

状态设置好后，会调用 `fatalthrow` 方法进行真正的 crash 相关操作：

```go
func fatalthrow() {
	pc := getcallerpc()
	sp := getcallersp()
	gp := getg()
	
	systemstack(func() {
		startpanic_m()
		if dopanic_m(gp, pc, sp) {
			crash()
		}

		exit(2)
	})

	*(*int)(nil) = 0 // not reached
}
```

主体逻辑是发送 `_SIGABRT` 信号量，最后调用 `exit` 方法退出，所以你会发现这是拦也拦不住的 “致命” 错误。

## 致命场景

为此，作为一名 “成熟” 的 Go 工程师，除了保障自己程序的健壮性外，我也在网上收集了一些致命的错误场景，分享给大家。

一起学习和规避这些致命场景，年底争取拿个 A，不要背上 P0 事故。

### 并发读写 map

```go
func foo() {
	m := map[string]int{}
	go func() {
		for {
			m["煎鱼1"] = 1
		}
	}()
	for {
		_ = m["煎鱼2"]
	}
}
```

输出结果：

```
fatal error: concurrent map read and map write

goroutine 1 [running]:
runtime.throw(0x1078103, 0x21)
...
```

### 堆栈内存耗尽

```go
func foo() {
	var f func(a [1000]int64)
	f = func(a [1000]int64) {
		f(a)
	}
	f([1000]int64{})
}
```

输出结果：

```
runtime: goroutine stack exceeds 1000000000-byte limit
runtime: sp=0xc0200e1bf0 stack=[0xc0200e0000, 0xc0400e0000]
fatal error: stack overflow

runtime stack:
runtime.throw(0x1074ba3, 0xe)
        /usr/local/Cellar/go/1.16.6/libexec/src/runtime/panic.go:1117 +0x72
runtime.newstack()
...
```

### 将 nil 函数作为 goroutine 启动

```go
func foo() {
	var f func()
	go f()
}
```

输出结果： 

```
fatal error: go of nil func value

goroutine 1 [running]:
main.foo()
...
```

### goroutines 死锁

```go
func foo() {
	select {}
}
```

输出结果：

```
fatal error: all goroutines are asleep - deadlock!

goroutine 1 [select (no cases)]:
main.foo()
...
```

### 线程限制耗尽

如果你的 goroutines 被 IO 操作阻塞了，新的线程可能会被启动来执行你的其他 goroutines。

Go 的最大的线程数是有默认限制的，如果达到了这个限制，你的应用程序就会崩溃。

会出现如下输出结果：

```
fatal error: thread exhaustion
...
```

可以通过调用 `runtime.SetMaxThreads` 方法增大线程数，不过也需要考量是否程序有问题。

### 超出可用内存

如果你执行的操作，例如：下载大文件等。导致应用程序占用内存过大，程序上涨，导致 OOM。

会出现如下输出结果：

```
fatal error: runtime: out of memory
...
```

建议处理掉一些程序，或者换新电脑了。

## 总结

在今天这篇文章中，我们介绍了 Go 语言的三种错误类型。其中针对大家最少见，但一碰到就很容易翻车的致命错误 fatal error 进行了介绍，给出了一些经典案例。

希望大家后续能够规避，**你有没有遇到过其中的场景**？

欢迎在评论区交流和留言：）

## 参考

- Are all runtime errors recoverable in Go?

================================================
FILE: content/posts/go/tools/2018-09-15-go-tool-pprof.md
================================================
---

title:      "Go 大杀器之性能剖析 PProf"
date:       2018-09-15 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

## 前言

写了几吨代码，实现了几百个接口。功能测试也通过了，终于成功的部署上线了

结果，性能不佳，什么鬼？😭

## 想做性能分析

### PProf

想要进行性能优化，首先瞩目在 Go 自身提供的工具链来作为分析依据，本文将带你学习、使用 Go 后花园，涉及如下：

- runtime/pprof：采集程序（非 Server）的运行数据进行分析
- net/http/pprof：采集 HTTP Server 的运行时数据进行分析

### 是什么

pprof 是用于可视化和分析性能分析数据的工具

pprof 以 [profile.proto](https://github.com/google/pprof/blob/master/proto/profile.proto) 读取分析样本的集合，并生成报告以可视化并帮助分析数据（支持文本和图形报告）

profile.proto 是一个 Protocol Buffer v3 的描述文件，它描述了一组 callstack 和 symbolization 信息， 作用是表示统计分析的一组采样的调用栈，是很常见的 stacktrace 配置文件格式

### 支持什么使用模式

- Report generation：报告生成
- Interactive terminal use：交互式终端使用
- Web interface：Web 界面

### 可以做什么

- CPU Profiling：CPU 分析，按照一定的频率采集所监听的应用程序 CPU（含寄存器）的使用情况，可确定应用程序在主动消耗 CPU 周期时花费时间的位置
- Memory Profiling：内存分析，在应用程序进行堆分配时记录堆栈跟踪，用于监视当前和历史内存使用情况，以及检查内存泄漏
- Block Profiling：阻塞分析，记录 goroutine 阻塞等待同步（包括定时器通道）的位置
- Mutex Profiling：互斥锁分析，报告互斥锁的竞争情况

## 一个简单的例子

我们将编写一个简单且有点问题的例子，用于基本的程序初步分析

### 编写 demo 文件

（1）demo.go，文件内容：

```go
package main

import (
	"log"
	"net/http"
	_ "net/http/pprof"
	"github.com/EDDYCJY/go-pprof-example/data"
)

func main() {
	go func() {
		for {
			log.Println(data.Add("https://github.com/EDDYCJY"))
		}
	}()

	http.ListenAndServe("0.0.0.0:6060", nil)
}
```

（2）data/d.go，文件内容：

```go
package data

var datas []string

func Add(str string) string {
	data := []byte(str)
	sData := string(data)
	datas = append(datas, sData)

	return sData
}

```

运行这个文件，你的 HTTP 服务会多出 /debug/pprof 的 endpoint 可用于观察应用程序的情况

### 分析

#### 一、通过 Web 界面

查看当前总览：访问 `http://127.0.0.1:6060/debug/pprof/`

```
/debug/pprof/

profiles:
0	block
5	goroutine
3	heap
0	mutex
9	threadcreate

full goroutine stack dump
```

这个页面中有许多子页面，咱们继续深究下去，看看可以得到什么？

- cpu（CPU Profiling）: `$HOST/debug/pprof/profile`，默认进行 30s 的 CPU Profiling，得到一个分析用的 profile 文件
- block（Block Profiling）：`$HOST/debug/pprof/block`，查看导致阻塞同步的堆栈跟踪
- goroutine：`$HOST/debug/pprof/goroutine`，查看当前所有运行的 goroutines 堆栈跟踪
- heap（Memory Profiling）: `$HOST/debug/pprof/heap`，查看活动对象的内存分配情况
- mutex（Mutex Profiling）：`$HOST/debug/pprof/mutex`，查看导致互斥锁的竞争持有者的堆栈跟踪
- threadcreate：`$HOST/debug/pprof/threadcreate`，查看创建新 OS 线程的堆栈跟踪

#### 二、通过交互式终端使用

（1）go tool pprof http://localhost:6060/debug/pprof/profile?seconds=60

```sh
$ go tool pprof http://localhost:6060/debug/pprof/profile\?seconds\=60

Fetching profile over HTTP from http://localhost:6060/debug/pprof/profile?seconds=60
Saved profile in /Users/eddycjy/pprof/pprof.samples.cpu.007.pb.gz
Type: cpu
Duration: 1mins, Total samples = 26.55s (44.15%)
Entering interactive mode (type "help" for commands, "o" for options)
(pprof)
```

执行该命令后，需等待 60 秒（可调整 seconds 的值），pprof 会进行 CPU Profiling。结束后将默认进入 pprof 的交互式命令模式，可以对分析的结果进行查看或导出。具体可执行 `pprof help` 查看命令说明

```sh
(pprof) top10
Showing nodes accounting for 25.92s, 97.63% of 26.55s total
Dropped 85 nodes (cum <= 0.13s)
Showing top 10 nodes out of 21
      flat  flat%   sum%        cum   cum%
    23.28s 87.68% 87.68%     23.29s 87.72%  syscall.Syscall
     0.77s  2.90% 90.58%      0.77s  2.90%  runtime.memmove
     0.58s  2.18% 92.77%      0.58s  2.18%  runtime.freedefer
     0.53s  2.00% 94.76%      1.42s  5.35%  runtime.scanobject
     0.36s  1.36% 96.12%      0.39s  1.47%  runtime.heapBitsForObject
     0.35s  1.32% 97.44%      0.45s  1.69%  runtime.greyobject
     0.02s 0.075% 97.51%     24.96s 94.01%  main.main.func1
     0.01s 0.038% 97.55%     23.91s 90.06%  os.(*File).Write
     0.01s 0.038% 97.59%      0.19s  0.72%  runtime.mallocgc
     0.01s 0.038% 97.63%     23.30s 87.76%  syscall.Write
```

- flat：给定函数上运行耗时
- flat%：同上的 CPU 运行耗时总比例
- sum%：给定函数累积使用 CPU 总比例
- cum：当前函数加上它之上的调用运行总耗时
- cum%：同上的 CPU 运行耗时总比例

最后一列为函数名称，在大多数的情况下，我们可以通过这五列得出一个应用程序的运行情况，加以优化 🤔

（2）go tool pprof http://localhost:6060/debug/pprof/heap

```sh
$ go tool pprof http://localhost:6060/debug/pprof/heap
Fetching profile over HTTP from http://localhost:6060/debug/pprof/heap
Saved profile in /Users/eddycjy/pprof/pprof.alloc_objects.alloc_space.inuse_objects.inuse_space.008.pb.gz
Type: inuse_space
Entering interactive mode (type "help" for commands, "o" for options)
(pprof) top
Showing nodes accounting for 837.48MB, 100% of 837.48MB total
      flat  flat%   sum%        cum   cum%
  837.48MB   100%   100%   837.48MB   100%  main.main.func1
```

- -inuse_space：分析应用程序的常驻内存占用情况

- -alloc_objects：分析应用程序的内存临时分配情况

（3） go tool pprof http://localhost:6060/debug/pprof/block

（4） go tool pprof http://localhost:6060/debug/pprof/mutex

#### 三、PProf 可视化界面

这是令人期待的一小节。在这之前，我们需要简单的编写好测试用例来跑一下

##### 编写测试用例

（1）新建 data/d_test.go，文件内容：

```go
package data

import "testing"

const url = "https://github.com/EDDYCJY"

func TestAdd(t *testing.T) {
	s := Add(url)
	if s == "" {
		t.Errorf("Test.Add error!")
	}
}

func BenchmarkAdd(b *testing.B) {
	for i := 0; i < b.N; i++ {
		Add(url)
	}
}
```

（2）执行测试用例

```
$ go test -bench=. -cpuprofile=cpu.prof
pkg: github.com/EDDYCJY/go-pprof-example/data
BenchmarkAdd-4   	10000000	       187 ns/op
PASS
ok  	github.com/EDDYCJY/go-pprof-example/data	2.300s
```

-memprofile 也可以了解一下

##### 启动 PProf 可视化界面

###### 方法一：

```
$ go tool pprof -http=:8080 cpu.prof
```

###### 方法二：

```
$ go tool pprof cpu.prof
$ (pprof) web
```

如果出现 `Could not execute dot; may need to install graphviz.`，就是提示你要安装 `graphviz` 了 （请右拐谷歌）

##### 查看 PProf 可视化界面

（1）Top

![image](https://s2.ax1x.com/2020/02/15/1xlsYD.jpg)

（2）Graph

![image](https://s2.ax1x.com/2020/02/15/1xlgld.jpg)

框越大，线越粗代表它占用的时间越大哦

（3）Peek

![image](https://s2.ax1x.com/2020/02/15/1xlROI.jpg)

（4）Source

![image](https://s2.ax1x.com/2020/02/15/1xl4Tf.jpg)

通过 PProf 的可视化界面，我们能够更方便、更直观的看到 Go 应用程序的调用链、使用情况等，并且在 View 菜单栏中，还支持如上多种方式的切换

你想想，在烦恼不知道什么问题的时候，能用这些辅助工具来检测问题，是不是瞬间效率翻倍了呢 👌

#### 四、PProf 火焰图

另一种可视化数据的方法是火焰图，需手动安装原生 PProf 工具：

（1） 安装 PProf

```
$ go get -u github.com/google/pprof
```

（2） 启动 PProf 可视化界面:

```
$ pprof -http=:8080 cpu.prof
```

（3） 查看 PProf 可视化界面

打开 PProf 的可视化界面时，你会明显发现比官方工具链的 PProf 精致一些，并且多了 Flame Graph（火焰图）

它就是本次的目标之一，它的最大优点是动态的。调用顺序由上到下（A -> B -> C -> D），每一块代表一个函数，越大代表占用 CPU 的时间更长。同时它也支持点击块深入进行分析！

![image](https://s2.ax1x.com/2020/02/15/1xlj00.jpg)

## 总结

在本章节，粗略地介绍了 Go 的性能利器 PProf。在特定的场景中，PProf 给定位、剖析问题带了极大的帮助

希望本文对你有所帮助，另外建议能够自己实际操作一遍，最好是可以深入琢磨一下，内含大量的用法、知识点 🤓

## 思考题

你很优秀的看到了最后，那么有两道简单的思考题，希望拓展你的思路

（1）flat 一定大于 cum 吗，为什么？什么场景下 cum 会比 flat 大？

（2）本章节的 demo 代码，有什么性能问题？怎么解决它？


================================================
FILE: content/posts/go/tools/2019-07-12-go-tool-trace.md
================================================
---

title:      "Go 大杀器之跟踪剖析 trace"
date:       2019-07-12 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://s2.ax1x.com/2020/02/15/1x1phF.png)

在 Go 中有许许多多的分析工具，在之前我有写过一篇 《Golang 大杀器之性能剖析 PProf》 来介绍 PProf，如果有小伙伴感兴趣可以去我博客看看。

但单单使用 PProf 有时候不一定足够完整，因为在真实的程序中还包含许多的隐藏动作，例如 Goroutine 在执行时会做哪些操作？执行/阻塞了多长时间？在什么时候阻止？在哪里被阻止的？谁又锁/解锁了它们？GC 是怎么影响到 Goroutine 的执行的？这些东西用 PProf 是很难分析出来的，但如果你又想知道上述的答案的话，你可以用本文的主角 `go tool trace` 来打开新世界的大门。目录如下：

![image](https://s2.ax1x.com/2020/02/15/1x1P1J.png)

## 初步了解

```go
import (
	"os"
	"runtime/trace"
)

func main() {
	trace.Start(os.Stderr)
	defer trace.Stop()

	ch := make(chan string)
	go func() {
		ch <- "EDDYCJY"
	}()

	<-ch
}
```

生成跟踪文件：

```
$ go run main.go 2> trace.out
```

启动可视化界面：

```
$ go tool trace trace.out
2019/06/22 16:14:52 Parsing trace...
2019/06/22 16:14:52 Splitting trace...
2019/06/22 16:14:52 Opening browser. Trace viewer is listening on http://127.0.0.1:57321
```

查看可视化界面：

![image](https://s2.ax1x.com/2020/02/15/1x1FXR.png)

- View trace：查看跟踪
- Goroutine analysis：Goroutine 分析
- Network blocking profile：网络阻塞概况
- Synchronization blocking profile：同步阻塞概况
- Syscall blocking profile：系统调用阻塞概况
- Scheduler latency profile：调度延迟概况
- User defined tasks：用户自定义任务
- User defined regions：用户自定义区域
- Minimum mutator utilization：最低 Mutator 利用率

### Scheduler latency profile

在刚开始查看问题时，除非是很明显的现象，否则不应该一开始就陷入细节，因此我们一般先查看 “Scheduler latency profile”，我们能通过 Graph 看到整体的调用开销情况，如下：

![image](https://s2.ax1x.com/2020/02/15/1x1K9e.png)

演示程序比较简单，因此这里就两块，一个是 `trace` 本身，另外一个是 `channel` 的收发。

### Goroutine analysis

第二步看 “Goroutine analysis”，我们能通过这个功能看到整个运行过程中，每个函数块有多少个有 Goroutine 在跑，并且观察每个的 Goroutine 的运行开销都花费在哪个阶段。如下：

![image](https://s2.ax1x.com/2020/02/15/1x1ljA.png)

通过上图我们可以看到共有 3 个 goroutine，分别是 `runtime.main`、`runtime/trace.Start.func1`、`main.main.func1`，那么它都做了些什么事呢，接下来我们可以通过点击具体细项去观察。如下：

![image](https://s2.ax1x.com/2020/02/15/1x18Bt.jpg)

同时也可以看到当前 Goroutine 在整个调用耗时中的占比，以及 GC 清扫和 GC 暂停等待的一些开销。如果你觉得还不够，可以把图表下载下来分析，相当于把整个 Goroutine 运行时掰开来看了，这块能够很好的帮助我们**对 Goroutine 运行阶段做一个的剖析，可以得知到底慢哪，然后再决定下一步的排查方向**。如下：

| 名称                  | 含义         | 耗时   |
| --------------------- | ------------ | ------ |
| Execution Time        | 执行时间     | 3140ns |
| Network Wait Time     | 网络等待时间 | 0ns    |
| Sync Block Time       | 同步阻塞时间 | 0ns    |
| Blocking Syscall Time | 调用阻塞时间 | 0ns    |
| Scheduler Wait Time   | 调度等待时间 | 14ns   |
| GC Sweeping           | GC 清扫      | 0ns    |
| GC Pause              | GC 暂停      | 0ns    |

### View trace

在对当前程序的 Goroutine 运行分布有了初步了解后，我们再通过 “查看跟踪” 看看之间的关联性，如下：

![image](https://s2.ax1x.com/2020/02/15/1x1GHP.png)

这个跟踪图粗略一看，相信有的小伙伴会比较懵逼，我们可以依据注解一块块查看，如下：

1. 时间线：显示执行的时间单元，根据时间维度的不同可以调整区间，具体可执行 `shift` + `?` 查看帮助手册。
2. 堆：显示执行期间的内存分配和释放情况。
3. 协程：显示在执行期间的每个 Goroutine 运行阶段有多少个协程在运行，其包含 GC 等待（GCWaiting）、可运行（Runnable）、运行中（Running）这三种状态。
4. OS 线程：显示在执行期间有多少个线程在运行，其包含正在调用 Syscall（InSyscall）、运行中（Running）这两种状态。
5. 虚拟处理器：每个虚拟处理器显示一行，虚拟处理器的数量一般默认为系统内核数。
6. 协程和事件：显示在每个虚拟处理器上有什么 Goroutine 正在运行，而连线行为代表事件关联。

![image](https://s2.ax1x.com/2020/02/15/1x1YAf.jpg)

点击具体的 Goroutine 行为后可以看到其相关联的详细信息，这块很简单，大家实际操作一下就懂了。文字解释如下：

- Start：开始时间
- Wall Duration：持续时间
- Self Time：执行时间
- Start Stack Trace：开始时的堆栈信息
- End Stack Trace：结束时的堆栈信息
- Incoming flow：输入流
- Outgoing flow：输出流
- Preceding events：之前的事件
- Following events：之后的事件
- All connected：所有连接的事件

### View Events

我们可以通过点击 View Options-Flow events、Following events 等方式，查看我们应用运行中的事件流情况。如下：

![image](https://s2.ax1x.com/2020/02/15/1x1d3Q.png)

通过分析图上的事件流，我们可得知这程序从 `G1 runtime.main` 开始运行，在运行时创建了 2 个 Goroutine，先是创建 `G18 runtime/trace.Start.func1`，然后再是 `G19 main.main.func1` 。而同时我们可以通过其 Goroutine Name 去了解它的调用类型，如：`runtime/trace.Start.func1` 就是程序中在 `main.main` 调用了 `runtime/trace.Start` 方法，然后该方法又利用协程创建了一个闭包 `func1` 去进行调用。

![image](https://s2.ax1x.com/2020/02/15/1x1Dun.png)

在这里我们结合开头的代码去看的话，很明显就是 `ch` 的输入输出的过程了。

## 结合实战

今天生产环境突然出现了问题，机智的你早已埋好 `_ "net/http/pprof"` 这个神奇的工具，你麻利的执行了如下命令：

- curl http://127.0.0.1:6060/debug/pprof/trace\?seconds\=20 > trace.out
- go tool trace trace.out

### View trace

你很快的看到了熟悉的 List 界面，然后不信邪点开了 View trace 界面，如下：

![image](https://s2.ax1x.com/2020/02/15/1x1cNT.jpg)

完全看懵的你，稳住，对着合适的区域执行快捷键 `W` 不断地放大时间线，如下：

![image](https://s2.ax1x.com/2020/02/15/1x1ID1.jpg)

经过初步排查，你发现上述绝大部分的 G 竟然都和 `google.golang.org/grpc.(*Server).Serve.func` 有关，关联的一大串也是 `Serve` 所触发的相关动作。

![image](https://s2.ax1x.com/2020/02/16/3pNw9I.jpg)

这时候有经验的你心里已经有了初步结论，你可以继续追踪 View trace 深入进去，不过我建议先鸟瞰全貌，因此我们再往下看 “Network blocking profile” 和 “Syscall blocking profile” 所提供的信息，如下：

### Network blocking profile

![image](https://s2.ax1x.com/2020/02/16/3pNfCn.jpg)

### Syscall blocking profile

![image](https://s2.ax1x.com/2020/02/16/3pN7bF.jpg)

通过对以上三项的跟踪分析，加上这个泄露，这个阻塞的耗时，这个涉及的内部方法名，很明显就是哪位又忘记关闭客户端连接了，赶紧改改改。

## 总结

通过本文我们习得了 `go tool trace` 的武林秘籍，它能够跟踪捕获各种执行中的事件，例如 Goroutine 的创建/阻塞/解除阻塞，Syscall 的进入/退出/阻止，GC 事件，Heap 的大小改变，Processor 启动/停止等等。

希望你能够用好 Go 的两大杀器 pprof + trace 组合，此乃排查好搭档，谁用谁清楚，即使他并不万能。

## 参考

- https://about.sourcegraph.com/go/an-introduction-to-go-tool-trace-rhys-hiltner
- https://www.itcodemonkey.com/article/5419.html
- https://making.pusher.com/go-tool-trace/
- https://golang.org/cmd/trace/
- https://docs.google.com/document/d/1FP5apqzBgr7ahCCgFO-yoVhk4YZrNIDNf9RybngBc14/pub
- https://godoc.org/runtime/trace

================================================
FILE: content/posts/go/tools/2019-08-19-godebug-sched.md
================================================
---

title:      "用 GODEBUG 看调度跟踪"
date:       2019-08-19 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://image.eddycjy.com/b01c2ce25e34f80d499f0488d034b00b.png)

让 Go 更强大的原因之一莫过于它的 GODEBUG 工具，GODEBUG 的设置可以让 Go 程序在运行时输出调试信息，可以根据你的要求很直观的看到你想要的调度器或垃圾回收等详细信息，并且还不需要加装其它的插件，非常方便，今天我们将先讲解 GODEBUG 的调度器相关内容，希望对你有所帮助。

不过在开始前，没接触过的小伙伴得先补补如下前置知识，便于更好的了解调试器输出的信息内容。

## 前置知识

Go scheduler 的主要功能是针对在处理器上运行的 OS 线程分发可运行的 Goroutine，而我们一提到调度器，就离不开三个经常被提到的缩写，分别是：

- G：Goroutine，实际上我们每次调用 `go func` 就是生成了一个 G。
- P：处理器，一般为处理器的核数，可以通过 `GOMAXPROCS` 进行修改。
- M：OS 线程

这三者交互实际来源于 Go 的 M: N 调度模型，也就是 M 必须与 P 进行绑定，然后不断地在 M 上循环寻找可运行的 G 来执行相应的任务，如果想具体了解可以详细阅读 [《Go Runtime Scheduler》](https://speakerdeck.com/retervision/go-runtime-scheduler)，我们抽其中的工作流程图进行简单分析，如下:

![image](https://image.eddycjy.com/fb4c6c92c93af3bc2dfc4f13dc167cdf.png)

1. 当我们执行 `go func()` 时，实际上就是创建一个全新的 Goroutine，我们称它为 G。
2. 新创建的 G 会被放入 P 的本地队列（Local Queue）或全局队列（Global Queue）中，准备下一步的动作。
3. 唤醒或创建 M 以便执行 G。
4. 不断地进行事件循环
5. 寻找在可用状态下的 G 进行执行任务
6. 清除后，重新进入事件循环

而在描述中有提到全局和本地这两类队列，其实在功能上来讲都是用于存放正在等待运行的 G，但是不同点在于，本地队列有数量限制，不允许超过 256 个。并且在新建 G 时，会优先选择 P 的本地队列，如果本地队列满了，则将 P 的本地队列的一半的 G 移动到全局队列，这其实可以理解为调度资源的共享和再平衡。

另外我们可以看到图上有 steal 行为，这是用来做什么的呢，我们都知道当你创建新的 G 或者 G 变成可运行状态时，它会被推送加入到当前 P 的本地队列中。但其实当 P 执行 G 完毕后，它也会 “干活”，它会将其从本地队列中弹出 G，同时会检查当前本地队列是否为空，如果为空会随机的从其他 P 的本地队列中尝试窃取一半可运行的 G 到自己的名下。例子如下：

![image](https://image.eddycjy.com/e7ca8f212466d8c15ec0f60b69a1ce4d.png)

在这个例子中，P2 在本地队列中找不到可以运行的 G，它会执行 `work-stealing` 调度算法，随机选择其它的处理器 P1，并从 P1 的本地队列中窃取了三个 G 到它自己的本地队列中去。至此，P1、P2 都拥有了可运行的 G，P1 多余的 G 也不会被浪费，调度资源将会更加平均的在多个处理器中流转。

## GODEBUG

GODEBUG 变量可以控制运行时内的调试变量，参数以逗号分隔，格式为：`name=val`。本文着重点在调度器观察上，将会使用如下两个参数：

- schedtrace：设置 `schedtrace=X` 参数可以使运行时在每 X 毫秒发出一行调度器的摘要信息到标准 err 输出中。
- scheddetail：设置 `schedtrace=X` 和 `scheddetail=1` 可以使运行时在每 X 毫秒发出一次详细的多行信息，信息内容主要包括调度程序、处理器、OS 线程 和 Goroutine 的状态。

### 演示代码

```
func main() {
	wg := sync.WaitGroup{}
	wg.Add(10)
	for i := 0; i < 10; i++ {
		go func(wg *sync.WaitGroup) {
			var counter int
			for i := 0; i < 1e10; i++ {
				counter++
			}
			wg.Done()
		}(&wg)
	}

	wg.Wait()
}
```

### schedtrace

```
$ GODEBUG=schedtrace=1000 ./awesomeProject 
SCHED 0ms: gomaxprocs=4 idleprocs=1 threads=5 spinningthreads=1 idlethreads=0 runqueue=0 [0 0 0 0]
SCHED 1000ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 [1 2 2 1]
SCHED 2000ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 [1 2 2 1]
SCHED 3001ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 [1 2 2 1]
SCHED 4010ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 [1 2 2 1]
SCHED 5011ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 [1 2 2 1]
SCHED 6012ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 [1 2 2 1]
SCHED 7021ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 8023ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 9031ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 10033ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 11038ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 12044ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 13051ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=4 [0 1 1 0]
SCHED 14052ms: gomaxprocs=4 idleprocs=2 threads=5 
...
```
- sched：每一行都代表调度器的调试信息，后面提示的毫秒数表示启动到现在的运行时间，输出的时间间隔受 `schedtrace` 的值影响。
- gomaxprocs：当前的 CPU 核心数（GOMAXPROCS 的当前值）。
- idleprocs：空闲的处理器数量，后面的数字表示当前的空闲数量。
- threads：OS 线程数量，后面的数字表示当前正在运行的线程数量。
- spinningthreads：自旋状态的 OS 线程数量。
- idlethreads：空闲的线程数量。
- runqueue：全局队列中中的 Goroutine 数量，而后面的 [0 0 1 1] 则分别代表这 4 个 P 的本地队列正在运行的 Goroutine 数量。

在上面我们有提到 “自旋线程” 这个概念，如果你之前没有了解过相关概念，一听 “自旋” 肯定会比较懵，我们引用 《Head First of Golang Scheduler》 的内容来说明：
 
 > 自旋线程的这个说法，是因为 Go Scheduler 的设计者在考虑了 “OS 的资源利用率” 以及 “频繁的线程抢占给 OS 带来的负载” 之后，提出了 “Spinning Thread” 的概念。也就是当 “自旋线程” 没有找到可供其调度执行的 Goroutine 时，并不会销毁该线程 ，而是采取 “自旋” 的操作保存了下来。虽然看起来这是浪费了一些资源，但是考虑一下 syscall 的情景就可以知道，比起 “自旋"，线程间频繁的抢占以及频繁的创建和销毁操作可能带来的危害会更大。

### scheddetail

如果我们想要更详细的看到调度器的完整信息时，我们可以增加 `scheddetail` 参数，就能够更进一步的查看调度的细节逻辑，如下：

```
$ GODEBUG=scheddetail=1,schedtrace=1000 ./awesomeProject
SCHED 1000ms: gomaxprocs=4 idleprocs=0 threads=5 spinningthreads=0 idlethreads=0 runqueue=0 gcwaiting=0 nmidlelocked=0 stopwait=0 sysmonwait=0
  P0: status=1 schedtick=2 syscalltick=0 m=3 runqsize=3 gfreecnt=0
  P1: status=1 schedtick=2 syscalltick=0 m=4 runqsize=1 gfreecnt=0
  P2: status=1 schedtick=2 syscalltick=0 m=0 runqsize=1 gfreecnt=0
  P3: status=1 schedtick=1 syscalltick=0 m=2 runqsize=1 gfreecnt=0
  M4: p=1 curg=18 mallocing=0 throwing=0 preemptoff= locks=0 dying=0 spinning=false blocked=false lockedg=-1
  M3: p=0 curg=22 mallocing=0 throwing=0 preemptoff= locks=0 dying=0 spinning=false blocked=false lockedg=-1
  M2: p=3 curg=24 mallocing=0 throwing=0 preemptoff= locks=0 dying=0 spinning=false blocked=false lockedg=-1
  M1: p=-1 curg=-1 mallocing=0 throwing=0 preemptoff= locks=1 dying=0 spinning=false blocked=false lockedg=-1
  M0: p=2 curg=26 mallocing=0 throwing=0 preemptoff= locks=0 dying=0 spinning=false blocked=false lockedg=-1
  G1: status=4(semacquire) m=-1 lockedm=-1
  G2: status=4(force gc (idle)) m=-1 lockedm=-1
  G3: status=4(GC sweep wait) m=-1 lockedm=-1
  G17: status=1() m=-1 lockedm=-1
  G18: status=2() m=4 lockedm=-1
  G19: status=1() m=-1 lockedm=-1
  G20: status=1() m=-1 lockedm=-1
  G21: status=1() m=-1 lockedm=-1
  G22: status=2() m=3 lockedm=-1
  G23: status=1() m=-1 lockedm=-1
  G24: status=2() m=2 lockedm=-1
  G25: status=1() m=-1 lockedm=-1
  G26: status=2() m=0 lockedm=-1
```

在这里我们抽取了 1000ms 时的调试信息来查看，信息量比较大，我们先从每一个字段开始了解。如下：

#### G

- status：G 的运行状态。
- m：隶属哪一个 M。
- lockedm：是否有锁定 M。

在第一点中我们有提到 G 的运行状态，这对于分析内部流转非常的有用，共涉及如下 9 种状态：

状态 | 值 | 含义
---|---| ---
_Gidle | 0 | 刚刚被分配，还没有进行初始化。
_Grunnable | 1 | 已经在运行队列中，还没有执行用户代码。
_Grunning | 2 | 不在运行队列里中，已经可以执行用户代码，此时已经分配了 M 和 P。
_Gsyscall | 3 | 正在执行系统调用，此时分配了 M。
_Gwaiting | 4 | 在运行时被阻止，没有执行用户代码，也不在运行队列中，此时它正在某处阻塞等待中。
_Gmoribund_unused | 5 | 尚未使用，但是在 gdb 中进行了硬编码。
_Gdead | 6 | 尚未使用，这个状态可能是刚退出或是刚被初始化，此时它并没有执行用户代码，有可能有也有可能没有分配堆栈。
_Genqueue_unused | 7 | 尚未使用。
_Gcopystack | 8 | 正在复制堆栈，并没有执行用户代码，也不在运行队列中。

在理解了各类的状态的意思后，我们结合上述案例看看，如下：

```
G1: status=4(semacquire) m=-1 lockedm=-1
G2: status=4(force gc (idle)) m=-1 lockedm=-1
G3: status=4(GC sweep wait) m=-1 lockedm=-1
G17: status=1() m=-1 lockedm=-1
G18: status=2() m=4 lockedm=-1
```

在这个片段中，G1 的运行状态为 `_Gwaiting`，并没有分配 M 和锁定。这时候你可能好奇在片段中括号里的是什么东西呢，其实是因为该 `status=4` 是表示 `Goroutine` 在**运行时时被阻止**，而阻止它的事件就是 `semacquire` 事件，是因为 `semacquire` 会检查信号量的情况，在合适的时机就调用 `goparkunlock` 函数，把当前 `Goroutine` 放进等待队列，并把它设为 `_Gwaiting` 状态。

那么在实际运行中还有什么原因会导致这种现象呢，我们一起看看，如下：

```
	waitReasonZero                                    // ""
	waitReasonGCAssistMarking                         // "GC assist marking"
	waitReasonIOWait                                  // "IO wait"
	waitReasonChanReceiveNilChan                      // "chan receive (nil chan)"
	waitReasonChanSendNilChan                         // "chan send (nil chan)"
	waitReasonDumpingHeap                             // "dumping heap"
	waitReasonGarbageCollection                       // "garbage collection"
	waitReasonGarbageCollectionScan                   // "garbage collection scan"
	waitReasonPanicWait                               // "panicwait"
	waitReasonSelect                                  // "select"
	waitReasonSelectNoCases                           // "select (no cases)"
	waitReasonGCAssistWait                            // "GC assist wait"
	waitReasonGCSweepWait                             // "GC sweep wait"
	waitReasonChanReceive                             // "chan receive"
	waitReasonChanSend                                // "chan send"
	waitReasonFinalizerWait                           // "finalizer wait"
	waitReasonForceGGIdle                             // "force gc (idle)"
	waitReasonSemacquire                              // "semacquire"
	waitReasonSleep                                   // "sleep"
	waitReasonSyncCondWait                            // "sync.Cond.Wait"
	waitReasonTimerGoroutineIdle                      // "timer goroutine (idle)"
	waitReasonTraceReaderBlocked                      // "trace reader (blocked)"
	waitReasonWaitForGCCycle                          // "wait for GC cycle"
	waitReasonGCWorkerIdle                            // "GC worker (idle)"
```

我们通过以上 `waitReason` 可以了解到 `Goroutine` 会被暂停运行的原因要素，也就是会出现在括号中的事件。

#### M

- p：隶属哪一个 P。
- curg：当前正在使用哪个 G。
- runqsize：运行队列中的 G 数量。
- gfreecnt：可用的G（状态为 Gdead）。
- mallocing：是否正在分配内存。
- throwing：是否抛出异常。
- preemptoff：不等于空字符串的话，保持 curg 在这个 m 上运行。

#### P

- status：P 的运行状态。
- schedtick：P 的调度次数。
- syscalltick：P 的系统调用次数。
- m：隶属哪一个 M。
- runqsize：运行队列中的 G 数量。
- gfreecnt：可用的G（状态为 Gdead）。

状态 | 值 | 含义
---|---| ---
_Pidle | 0 | 刚刚被分配，还没有进行进行初始化。
_Prunning | 1 | 当 M 与 P 绑定调用 acquirep 时，P 的状态会改变为 _Prunning。
_Psyscall | 2 | 正在执行系统调用。
_Pgcstop | 3 | 暂停运行，此时系统正在进行 GC，直至 GC 结束后才会转变到下一个状态阶段。
_Pdead | 4 | 废弃，不再使用。

## 总结

通过本文我们学习到了调度的一些基础知识，再通过神奇的 GODEBUG 掌握了观察调度器的方式方法，你想想，是不是可以和我上一篇文章的 `go tool trace` 来结合使用呢，在实际的使用中，类似的办法有很多，组合巧用是重点。

## 参考

- [Debugging performance issues in Go programs](https://software.intel.com/en-us/blogs/2014/05/10/debugging-performance-issues-in-go-programs)
- [A whirlwind tour of Go’s runtime environment variables](https://dave.cheney.net/tag/godebug)
- [Go调度器系列（2）宏观看调度器](https://mp.weixin.qq.com/s?__biz=Mzg3MTA0NDQ1OQ==&mid=2247483907&idx=2&sn=c955372683bc0078e14227702ab0a35e&chksm=ce85c607f9f24f116158043f63f7ca11dc88cd519393ba182261f0d7fc328c7b6a94fef4e416&scene=38#wechat_redirect)
- [Go's work-stealing scheduler](https://rakyll.org/scheduler/)
- [Scheduler Tracing In Go](https://www.ardanlabs.com/blog/2015/02/scheduler-tracing-in-go.html)
- [Head First of Golang Scheduler](https://zhuanlan.zhihu.com/p/42057783)
- [goroutine 的状态切换](http://xargin.com/state-of-goroutine/)
- [Environment_Variables](https://golang.org/pkg/runtime/#hdr-Environment_Variables)

================================================
FILE: content/posts/go/tools/2019-09-02-godebug-gc.md
================================================
---

title:      "用 GODEBUG 看 GC"
date:       2019-09-02 12:00:00
author:     "煎鱼"
toc: true
tags:
    - go
---

![image](https://image.eddycjy.com/b07f55c7fd136392763729b9782f7776.png)

## 什么是 GC

在计算机科学中，垃圾回收（GC）是一种自动管理内存的机制，垃圾回收器会去尝试回收程序不再使用的对象及其占用的内存。而最早 John McCarthy 在 1959 年左右发明了垃圾回收，以简化 Lisp 中的手动内存管理的机制（来自 wikipedia）。

## 为什么要 GC

手动管理内存挺麻烦，管错或者管漏内存也很糟糕，将会直接导致程序不稳定（持续泄露）甚至直接崩溃。

## GC 带来的问题

硬要说会带来什么问题的话，也就数大家最关注的 Stop The World（STW），STW 代指在执行某个垃圾回收算法的某个阶段时，需要将整个应用程序暂停去处理 GC 相关的工作事项。例如：

行为 | 会不会 STW | 为什么
---|---|---
标记开始 | 会 | 在开始标记时，准备根对象的扫描，会打开写屏障（Write Barrier） 和 辅助GC（mutator assist），而回收器和应用程序是并发运行的，因此会暂停当前正在运行的所有 Goroutine。
并发标记中 | 不会 | 标记阶段，主要目的是标记堆内存中仍在使用的值。 
标记结束 | 会 | 在完成标记任务后，将重新扫描部分根对象，这时候会禁用写屏障（Write Barrier）和辅助GC（mutator assist），而标记阶段和应用程序是并发运行的，所以在标记阶段可能会有新的对象产生，因此在重新扫描时需要进行 STW。

## 如何调整 GC 频率

可以通过 GOGC 变量设置初始垃圾收集器的目标百分比值，对比的规则为当新分配的数值与上一次收集后剩余的实时数值的比例达到设置的目标百分比时，就会触发 GC，默认值为 GOGC=100。如果将其设置为 GOGC=off 可以完全禁用垃圾回收器，要不试试？

简单来讲就是，GOGC 的值设置的越大，GC 的频率越低，但每次最终所触发到 GC 的堆内存也会更大。

## 各版本 GC 情况

版本| GC 算法 | STW 时间
---|---|---
Go 1.0 | STW（强依赖 tcmalloc） | 百ms到秒级别
Go 1.3 | Mark STW, Sweep 并行 | 百ms级别
Go 1.5 | 三色标记法, 并发标记清除。同时运行时从 C 和少量汇编，改为 Go 和少量汇编实现 | 10-50ms级别
Go 1.6 | 1.5 中一些与并发 GC 不协调的地方更改，集中式的 GC 协调协程，改为状态机实现 | 5ms级别
Go 1.7 | GC 时由 mark 栈收缩改为并发，span 对象分配机制由 freelist 改为 bitmap 模式，SSA引入 | ms级别
Go 1.8 | 混合写屏障（hybrid write barrier）, 消除 re-scanning stack | sub ms
Go 1.12 | Mark Termination 流程优化 | sub ms, 但几乎减少一半 

注：资料来源于 @boya 在深圳 Gopher Meetup 的分享。

## GODEBUG

GODEBUG 变量可以控制运行时内的调试变量，参数以逗号分隔，格式为：`name=val`。本文着重点在 GC 的观察上，主要涉及 gctrace 参数，我们通过设置 `gctrace=1` 后就可以使得垃圾收集器向标准错误流发出 GC 运行信息。

## 涉及术语

- mark：标记阶段。
- markTermination：标记结束阶段。
- mutator assist：辅助 GC，是指在 GC 过程中 mutator 线程会并发运行，而 mutator assist 机制会协助 GC 做一部分的工作。
- heap_live：在 Go 的内存管理中，span 是内存页的基本单元，每页大小为 8kb，同时 Go 会根据对象的大小不同而分配不同页数的 span，而 heap_live 就代表着所有 span 的总大小。
- dedicated / fractional / idle：在标记阶段会分为三种不同的 mark worker 模式，分别是 dedicated、fractional 和 idle，它们代表着不同的专注程度，其中 dedicated 模式最专注，是完整的 GC 回收行为，fractional 只会干部分的 GC 行为，idle 最轻松。这里你只需要了解它是不同专注程度的 mark worker 就好了，详细介绍我们可以等后续的文章。

## 演示代码

```
func main() {
    wg := sync.WaitGroup{}
    wg.Add(10)
    for i := 0; i < 10; i++ {
        go func(wg *sync.WaitGroup) {
            var counter int
            for i := 0; i < 1e10; i++ {
                counter++
            }
            wg.Done()
        }(&wg)
    }

    wg.Wait()
}
```

## gctrace

```
$ GODEBUG=gctrace=1 go run main.go    
gc 1 @0.032s 0%: 0.019+0.45+0.003 ms clock, 0.076+0.22/0.40/0.80+0.012 ms cpu, 4->4->0 MB, 5 MB goal, 4 P
gc 2 @0.046s 0%: 0.004+0.40+0.008 ms clock, 0.017+0.32/0.25/0.81+0.034 ms cpu, 4->4->0 MB, 5 MB goal, 4 P
gc 3 @0.063s 0%: 0.004+0.40+0.008 ms clock, 0.018+0.056/0.32/0.64+0.033 ms cpu, 4->4->0 MB, 5 MB goal, 4 P
gc 4 @0.080s 0%: 0.004+0.45+0.016 ms clock, 0.018+0.15/0.34/0.77+0.065 ms cpu, 4->4->1 MB, 5 MB goal, 4 P
gc 5 @0.095s 0%: 0.015+0.87+0.005 ms clock, 0.061+0.27/0.74/1.8+0.023 ms cpu, 4->4->1 MB, 5 MB goal, 4 P
gc 6 @0.113s 0%: 0.014+0.69+0.002 ms clock, 0.056+0.23/0.48/1.4+0.011 ms cpu, 4->4->1 MB, 5 MB goal, 4 P
gc 7 @0.140s 1%: 0.031+2.0+0.042 ms clock, 0.12+0.43/1.8/0.049+0.17 ms cpu, 4->4->1 MB, 5 MB goal, 4 P
...
```

### 格式

```
gc # @#s #%: #+#+# ms clock, #+#/#/#+# ms cpu, #->#-># MB, # MB goal, # P
```

### 含义

- `gc#`：GC 执行次数的编号，每次叠加。
- `@#s`：自程序启动后到当前的具体秒数。
- `#%`：自程序启动以来在GC中花费的时间百分比。
- `#+...+#`：GC 的标记工作共使用的 CPU 时间占总 CPU 时间的百分比。
- `#->#-># MB`：分别表示 GC 启动时, GC 结束时, GC 活动时的堆大小.
- `#MB goal`：下一次触发 GC 的内存占用阈值。
- `#P`：当前使用的处理器 P 的数量。

### 案例

```
gc 7 @0.140s 1%: 0.031+2.0+0.042 ms clock, 0.12+0.43/1.8/0.049+0.17 ms cpu, 4->4->1 MB, 5 MB goal, 4 P
```
- gc 7：第 7 次 GC。
- @0.140s：当前是程序启动后的 0.140s。
- 1%：程序启动后到现在共花费 1% 的时间在 GC 上。
- 0.031+2.0+0.042 ms clock：
   - 0.031：表示单个 P 在 mark 阶段的 STW 时间。
   - 2.0：表示所有 P 的 mark concurrent（并发标记）所使用的时间。
   - 0.042：表示单个 P 的 markTermination 阶段的 STW 时间。
- 0.12+0.43/1.8/0.049+0.17 ms cpu：
   - 0.12：表示整个进程在 mark 阶段 STW 停顿的时间。
   - 0.43/1.8/0.049：0.43 表示 mutator assist 占用的时间，1.8 表示 dedicated + fractional 占用的时间，0.049 表示 idle 占用的时间。
   - 0.17ms：0.17 表示整个进程在 markTermination 阶段 STW 时间。
- 4->4->1 MB：
   - 4：表示开始 mark 阶段前的 heap_live 大小。
   - 4：表示开始 markTermination 阶段前的 heap_live 大小。
   - 1：表示被标记对象的大小。
- 5 MB goal：表示下一次触发 GC 回收的阈值是 5 MB。
- 4 P：本次 GC 一共涉及多少个 P。

## 总结

通过本章节我们掌握了使用 GODEBUG 查看应用程序 GC 运行情况的方法，只要用这种方法我们就可以观测不同情况下 GC 的情况了，甚至可以做出非常直观的对比图，大家不妨尝试一下。

## 关联文章

- [用 GODEBUG 看调度跟踪](https://mp.weixin.qq.com/s/Brby6D7d1szUIBjcD_8kfg)

## 参考

- [Go GC打印出来的这些信息都是什么含义？](https://gocn.vip/question/310)
- [GODEBUG之gctrace解析](http://cbsheng.github.io/posts/godebug%E4%B9%8Bgctrace%E8%A7%A3%E6%9E%90/)
- [关于Golang GC的一些误解--真的比Java GC更领先吗？](https://zhuanlan.zhihu.com/p/77943973)
- @boya 深入浅出Golang Runtime PPT


================================================
FILE: content/posts/go/type-after.md
================================================
---
title: "为什么 Go 语言把类型放在后面？"
date: 2021-12-31T12:55:10+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前段时间看到大家在吵一个话题，那就是 Go 语言的类型声明，抠知识抠的非常细了，就是为什么他要放在后面。

示例代码如下：

```golang
var a []string
var b []string
```

其实在早年 Go 官方估计已经被问烦了，写过一篇《[Go's Declaration Syntax](https://go.dev/blog/declaration-syntax "Go's Declaration Syntax")》来具体介绍和说明情况。

为此煎鱼将参考并结合这篇官方资料，带大家一起了解为什么 Go 如此的 “与众不同” ，为什么要把类型放在后面。

## 类型前置

在业内目前有不少知名语言，也采取的是在声明变量类型时，把类型定义在名字前面。像是 C、C++、C#、Java 等：

```c
int x;
int x = 100;
```

基本的格式定义：<data_type> <variable_list>;。

上面的声明是一个简单的例子，如果更复杂一些，Go 官方还给出了著名的函数指针的例子：

```c
int (*fp)(int a, int b);
```

更进一步，如果返回值也是个函数指针类型，就会变成：

```c
int (*(*fp)(int (*)(int, int), int))(int, int)
```

这已经很难看出来是个 fp 的声明了。

## 类型后置

前面所举例的类型前置的编程语言，很多都是 C 系列中的一者。类型后置的代表，分别有：Go、Rust、Scala、Kotlin 等。

其实在很多类型后置的编程语言种，会采取变量名+冒号+类型的方式出现。就像 Rust 一样：

```rust
let x: i32;
```

基本的格式定义：

```
x: int
p: pointer to int
a: array[3] of int
```

Go 官方参照了这类类型后置的设计，并且为了简洁，进一步去掉了冒号和一些关键字，变成：

```golang
var a []string
```

我们再看回前面 fp 的声明的例子：

```c
int (*(*fp)(int (*)(int, int), int))(int, int)
```

再对比 Go 语言中就变成了：

```golang
f func(func(int,int) int, int) func(int, int) int
```

两者一对比，Go 语言代码可读性确实更高一些。

## 思考

### 后置类别

在类型声明上，实际上分为：变量类型后置、函数返回值后置。两者共同构建了前置还是后置，总不能一个前置，一个后置吧，那得多么的难受。

上方 C 语言和 Go 语言函数指针的例子，所对比带来的代码可读性提高，其实本质上是由**函数返回值后置**所带来的。

和类型前置、后置没太多直接关系。

### 核心思想

在类型后置上来讲，Go 官方核心思想是：**这种声明方式（从左到右的风格）的一个优点是，当类型变得更加复杂时，它的效果非常好**（One merit of this left-to-right style is how well it works as the types become more complex）。

Go 的变量名总是在前，在人的代码阅读上可以**保持从左到右阅读**，不需要像 C 语言一样在一大堆声明中用技巧找变量名对应的类型。

![The Clockwise/Spiral Rule](https://files.mdnice.com/user/3610/b025d274-ae83-404c-8072-2776cd790708.png)

为此甚至有人写了篇 C 语言的顺时针读法《[The Clockwise/Spiral Rule](http://c-faq.com/decl/spiral.anderson.html "The Clockwise/Spiral Rule")》，有兴趣可以阅读。

如此一对比，Go 语言的类型后置在复杂场景下与 C 语言的对比确实更好一些。

### 其他因素

#### 类型推导

诸如在类型推导的形式上也会更直观：

```golang
func main() {
    var s1 := "脑子进煎鱼了"
    var s2 string
}
```

也是一个可读性提高的问题。

#### 类型和名字谁更重要

不同设计者对谁更重要的理解也不一样。是类型更重要，还是名字更重要呢？

有的人认为是类型，有的人认为是名字。这就真的是千人千面，众口难调了。

## C# 的后悔

我们看看其他语言，C# 设计组成员之一，其实在《[Sharp Regrets: Top 10 Worst C# Features](https://www.informit.com/articles/article.aspx?p=2425867 "Sharp Regrets: Top 10 Worst C# Features")》中的第五点表达了个人对类型前置、后置的设计教训。


![](https://files.mdnice.com/user/3610/6d5665b7-125f-4202-8742-c11c433566d7.png)

核心观点是：从编程和数学两方面来看，都有一个约定，即计算的结果在右侧表示，所以在类 C 语言中，类型在左侧是很奇怪的。

在设计时，C# 本来计划把类型注释放在右边。但考虑到类 C 语言，因此遵循了其他语言的惯例。


## 总结

实际上该问题的研讨，在 2021 年的现在，大部分 case 都一一被反驳了。类型后置也不是一个与众不同的设计，很多语言都是如此。但既然要讨论 Go 语言，那更多的是站在设计者的角度去考虑。

结合 Go 所提供的官方资料，在当年的目的更多的是为了**在遇到复杂类型定义时，能保持一定的代码可读性**。

当然，这不可否认肯定包含 Go 开发团队的主观意识。有兴趣的可以具体挖挖背后的信息。

如果是你，**你会把类型放在前面，还是后面呢，为什么**？

================================================
FILE: content/posts/go/unsafe-pointer.md
================================================
---
title: "详解 Go 团队不建议用的 unsafe.Pointer"
date: 2021-12-31T12:54:54+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

大家在学习 Go 的时候，肯定都学过 “Go 的指针是不支持指针运算和转换” 这个知识点。为什么呢？

首先，Go 是一门静态语言，所有的变量都必须为标量类型。不同的类型不能够进行赋值、计算等跨类型的操作。

那么指针也对应着相对的类型，也在 Compile 的静态类型检查的范围内。同时静态语言，也称为强类型。也就是一旦定义了，就不能再改变它。

错误的示例
-----

```
func main(){
 num := 5
 numPointer := &num

 flnum := (*float32)(numPointer)
 fmt.Println(flnum)
}
```

输出结果：

```
# command-line-arguments
...: cannot convert numPointer (type *int) to type *float32
```

在示例中，我们创建了一个 `num` 变量，值为 5，类型为 `int`，准备干一番大事。

接下来我们取了其对于的指针地址后，试图强制转换为 `*float32`，结果失败...

万能的破壁 unsafe
------------

针对刚刚的 “错误示例”，我们可以采用今天的男主角 `unsafe` 标准库来解决。它是一个神奇的包，在官方的诠释中，有如下概述：

*   围绕 Go 程序内存安全及类型的操作。
    
*   很可能会是不可移植的。
    
*   不受 Go 1 兼容性指南的保护。
    

简单来讲就是，不怎么推荐你使用，因为它是 unsafe（不安全的）。

但是在特殊的场景下，使用了它，可以打破 Go 的类型和内存安全机制，让你获得眼前一亮的惊喜效果。

### unsafe.Pointer

为了解决这个问题，需要用到 `unsafe.Pointer`。它表示任意类型且可寻址的指针值，可以在不同的指针类型之间进行转换（类似 C 语言的 void \* 的用途）。

其包含四种核心操作：

*   任何类型的指针值都可以转换为 Pointer。
    
*   Pointer 可以转换为任何类型的指针值。
    
*   uintptr 可以转换为 Pointer。
    
*   Pointer 可以转换为 uintptr。
    

在这一部分，重点看第一点、第二点。你再想想怎么修改 “错误的例子” 让它运行起来？

修改如下：  

```
func main(){
 num := 5
 numPointer := &num

 flnum := (*float32)(unsafe.Pointer(numPointer))
 fmt.Println(flnum)
}
```

输出结果：

```
0xc4200140b0
```

在上述代码中，我们小加改动。通过 `unsafe.Pointer` 的特性对该指针变量进行了修改，就可以完成任意类型（\*T）的指针转换。

需要注意的是，这时还无法对变量进行操作或访问，因为不知道该指针地址指向的东西具体是什么类型。不知道是什么类型，又如何进行解析呢？

无法解析也就自然无法对其变更了。

### unsafe.Offsetof

在上小节中，我们对普通的指针变量进行了修改。那么它是否能做更复杂一点的事呢？

```
type Num struct{
 i string
 j int64
}

func main(){
 n := Num{i: "EDDYCJY", j: 1}
 nPointer := unsafe.Pointer(&n)

 niPointer := (*string)(unsafe.Pointer(nPointer))
 *niPointer = "煎鱼"

 njPointer := (*int64)(unsafe.Pointer(uintptr(nPointer) + unsafe.Offsetof(n.j)))
 *njPointer = 2

 fmt.Printf("n.i: %s, n.j: %d", n.i, n.j)
}
```

输出结果：

```
n.i: 煎鱼, n.j: 2
```

在剖析这段代码做了什么事之前，我们需要了解结构体的一些基本概念：

*   结构体的成员变量在内存存储上是一段连续的内存。
    
*   结构体的初始地址就是第一个成员变量的内存地址。
    
*   基于结构体的成员地址去计算偏移量。就能够得出其他成员变量的内存地址。
    

再回来看看上述代码，得出执行流程：

*   修改 `n.i` 值：`i` 为第一个成员变量。因此不需要进行偏移量计算，直接取出指针后转换为 `Pointer`，再强制转换为字符串类型的指针值即可。
    
*   修改 `n.j` 值：`j` 为第二个成员变量。需要进行偏移量计算，才可以对其内存地址进行修改。在进行了偏移运算后，当前地址已经指向第二个成员变量。接着重复转换赋值即可。
    

### 细节分析

需要注意的是，这里使用了如下方法（来完成偏移计算的目标）：

1、uintptr：`uintptr` 是 Go 的内置类型。返回无符号整数，可存储一个完整的地址。后续常用于指针运算

```
type uintptr uintptr
```

2、unsafe.Offsetof：返回成员变量 x 在结构体当中的偏移量。更具体的讲，就是返回结构体初始位置到 x 之间的字节数。需要注意的是入参 `ArbitraryType` 表示任意类型，并非定义的 `int`。它实际作用是一个占位符

```
func Offsetof(x ArbitraryType) uintptr
```

在这一部分，其实就是巧用了 `Pointer` 的第三、第四点特性。这时候就已经可以对变量进行操作了。

### 糟糕的例子

```
func main(){
 n := Num{i: "EDDYCJY", j: 1}
 nPointer := unsafe.Pointer(&n)
 ...

 ptr := uintptr(nPointer)
 njPointer := (*int64)(unsafe.Pointer(ptr + unsafe.Offsetof(n.j)))
 ...
}
```

这里存在一个问题，`uintptr` 类型是不能存储在临时变量中的。因为从 GC 的角度来看，`uintptr` 类型的临时变量只是一个无符号整数，并不知道它是一个指针地址。

因此当满足一定条件后，`ptr` 这个临时变量是可能被垃圾回收掉的，那么接下来的内存操作，岂不成迷？

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，学习 Go 语言可以看 [Go 学习地图和路线](https://github.com/eddycjy/go-developer-roadmap)，欢迎 Star 催更。

总结
--

简洁回顾两个知识点，如下：

*   第一是 `unsafe.Pointer` 可以让你的变量在不同的指针类型转来转去，也就是表示为任意可寻址的指针类型。
    
*   第二是 `uintptr` 常用于与 `unsafe.Pointer` 打配合，用于做指针运算，巧妙地很。

================================================
FILE: content/posts/go/value-quote.md
================================================
---
title: "群里又吵起来了，Go 是传值还是传引用？"
date: 2021-12-31T12:54:52+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

前几天在咱们的 Go 交流群里，有一个小伙伴问了 “xxx 是不是引用类型？” 这个问题，引发了将近 5 小时的讨论：

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/9be6b8a7ae844766afa6c2a79c3666d5~tplv-k3u1fbpfcp-zoom-1.image)

兜兜转转回到了日经的问题，几乎每个月都要有人因此吵一架。就是 **Go 语言到底是传值（值传递），还是传引用（引用传递）**？

Go 官方的定义
--------

本部分引用 Go 官方 FAQ 的 “When are function parameters passed by value?”，内容如下。

如同 C 系列的所有语言一样，**Go 语言中的所有东西都是以值传递的**。也就是说，一个函数总是得到一个被传递的东西的副本，就像有一个赋值语句将值赋给参数一样。

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/4dc92546d5494e5b9a2a2a5083aa0a5b~tplv-k3u1fbpfcp-zoom-1.image)

例如：

*   向一个函数传递一个 int 值，就会得到 int 的副本。
    
    而传递一个指针值就会得到指针的副本，但不会得到它所指向的数据。
    
*   map 和 slice 的行为类似于指针：它们是包含指向底层 map 或 slice 数据的指针的描述符。
    

*   复制一个 map 或 slice 值并不会复制它所指向的数据。
    
*   复制一个接口值会复制存储在接口值中的东西。
    
*   如果接口值持有一个结构，复制接口值就会复制该结构。如果接口值持有一个指针，复制接口值会复制该指针，但同样不会复制它所指向的数据。
    

划重点，Go 语言中一切都是值传递，没有引用传递。不要直接把其他概念硬套上来，会犯先入为主的错误的。

传值和传引用
------

### 传值

传值，也叫做值传递（pass by value）。其**指的是在调用函数时将实际参数复制一份传递到函数中**，这样在函数中如果对参数进行修改，将不会影响到实际参数。

简单来讲，值传递，所传递的是该参数的副本，是复制了一份的，本质上不能认为是一个东西，指向的不是一个内存地址。

案例一如下：

```
func main() {
 s := "脑子进煎鱼了"
 fmt.Printf("main 内存地址：%p\n", &s)
 hello(&s)
}

func hello(s *string) {
 fmt.Printf("hello 内存地址：%p\n", &s)
}

```

输出结果：

```
main 内存地址：0xc000116220
hello 内存地址：0xc000132020

```

我们可以看到在 main 函数中的变量 s 所指向的内存地址是 `0xc000116220`。在经过 hello 函数的参数传递后，其在内部所输出的内存地址是 `0xc000132020`，两者发生了改变。

![图片](https://p3-juejin.byteimg.com/tos-cn-i-k3u1fbpfcp/d1610690706d432e9af21835d0d65ed3~tplv-k3u1fbpfcp-zoom-1.image)

据此我们可以得出结论，在 Go 语言确实都是值传递。那是不是在函数内修改值，就不会影响到 main 函数呢？

案例二如下：

```
func main() {
 s := "脑子进煎鱼了"
 fmt.Printf("main 内存地址：%p\n", &s)
 hello(&s)
 fmt.Println(s)
}

func hello(s *string) {
 fmt.Printf("hello 内存地址：%p\n", &s)
 *s = "煎鱼进脑子了"
}

```

我们在 hello 函数中修改了变量 s 的值，那么最后在 main 函数中我们所输出的变量 s 的值是什么呢。是 “脑子进煎鱼了”，还是 "煎鱼进脑子了"？

输出结果：

```
main 内存地址：0xc000010240
hello 内存地址：0xc00000e030
煎鱼进脑子了

```

输出的结果是 “煎鱼进脑子了”。这时候大家可能又犯嘀咕了，煎鱼前面明明说的是 Go 语言只有值传递，也验证了两者的内存地址，都是不一样的，怎么他这下他的值就改变了，这是为什么？

因为 “如果传过去的值是指向内存空间的地址，那么是可以对这块内存空间做修改的”。

也就是这两个内存地址，其实是指针的指针，其根源都指向着同一个指针，也就是指向着变量 s。因此我们进一步修改变量 s，得到输出 “煎鱼进脑子了” 的结果。

### 传引用

传引用，也叫做引用传递（pass by reference），**指在调用函数时将实际参数的地址直接传递到函数中**，那么在函数中对参数所进行的修改，将影响到实际参数。

在 Go 语言中，官方已经明确了没有传引用，也就是没有引用传递这一情况。

因此借用文字简单描述，像是例子中，即使你将参数传入，最终所输出的内存地址都是一样的。

争议最大的 map 和 slice
-----------------

这时候又有小伙伴疑惑了，你看 Go 语言中的 map 和 slice 类型，能直接修改，难道不是同个内存地址，不是引用了？

其实在 FAQ 中有一句提醒很重要：“map 和 slice 的行为类似于指针，它们是包含指向底层 map 或 slice 数据的指针的描述符”。

### map

针对 map 类型，进一步展开来看看例子：

```
func main() {
 m := make(map[string]string)
 m["脑子进煎鱼了"] = "这次一定！"
 fmt.Printf("main 内存地址：%p\n", &m)
 hello(m)

 fmt.Printf("%v", m)
}

func hello(p map[string]string) {
 fmt.Printf("hello 内存地址：%p\n", &p)
 p["脑子进煎鱼了"] = "记得点赞！"
}

```

输出结果：

```
main 内存地址：0xc00000e028
hello 内存地址：0xc00000e038
```

确实是值传递，那修改后的 map 的结果应该是什么。既然是值传递，那肯定就是 "这次一定！"，对吗？

输出结果：

```
map[脑子进煎鱼了:记得点赞！]
```

结果是修改成功，输出了 “记得点赞！”。这下就尴尬了，为什么是值传递，又还能做到类似引用的效果，能修改到源值呢？

这里的小窍门是：

```
func makemap(t *maptype, hint int, h *hmap) *hmap {}
```

这是创建 map 类型的底层 runtime 方法，注意其返回的是 `*hmap` 类型，是一个指针。也就是 Go 语言通过对 map 类型的相关方法进行封装，达到了用户需要关注指针传递的作用。

就是说当我们在调用 `hello` 方法时，其相当于是在传入一个指针参数 `hello(*hmap)`，与前面的值类型的案例二类似。

这类情况我们称其为 “引用类型”，但 “引用类型” 不等同于就是传引用，又或是引用传递了，还是有比较明确的区别的。

在 Go 语言中与 map 类型类似的还有 chan 类型：

```
func makechan(t *chantype, size int) *hchan {}
```

一样的效果。

### slice

针对 slice 类型，进一步展开来看看例子：

```
func main() {
 s := []string{"烤鱼", "咸鱼", "摸鱼"}
 fmt.Printf("main 内存地址：%p\n", s)
 hello(s)
 fmt.Println(s)
}

func hello(s []string) {
 fmt.Printf("hello 内存地址：%p\n", s)
 s[0] = "煎鱼"
}
```

输出结果：

```
main 内存地址：0xc000098180
hello 内存地址：0xc000098180
[煎鱼 咸鱼 摸鱼]
```

从结果来看，两者的内存地址一样，也成功的变更到了变量 s 的值。这难道不是引用传递吗，煎鱼翻车了？

关注两个细节：

*   没有用 `&` 来取地址。
    
*   可以直接用 `%p` 来打印。
    

之所以可以同时做到上面这两件事，是因为标准库 `fmt` 针对在这一块做了优化：  

```
func (p *pp) fmtPointer(value reflect.Value, verb rune) {
 var u uintptr
 switch value.Kind() {
 case reflect.Chan, reflect.Func, reflect.Map, reflect.Ptr, reflect.Slice, reflect.UnsafePointer:
  u = value.Pointer()
 default:
  p.badVerb(verb)
  return
 }
```

留意到代码 `value.Pointer`，标准库进行了特殊处理，直接对应的值的指针地址，当然就不需要取地址符了。

标准库 `fmt` 能够输出 slice 类型对应的值的原因也在此：

```
func (v Value) Pointer() uintptr {
 ...
 case Slice:
  return (*SliceHeader)(v.ptr).Data
 }
}

type SliceHeader struct {
 Data uintptr
 Len  int
 Cap  int
}
```

其在内部转换的 `Data` 属性，正正是 Go 语言中 slice 类型的运行时表现 SliceHeader。我们在调用 `%p` 输出时，是在输出 slice 的底层存储数组元素的地址。

下一个问题是：为什么 slice 类型可以直接修改源数据的值呢。

其实和输出的原理是一样的，在 Go 语言运行时，传递的也是相应 slice 类型的底层数组的指针，但需要注意，其使用的是指针的副本。严格意义是引用类型，依旧是值传递。

妙不妙？

总结
--

在今天这篇文章中，我们针对 Go 语言的日经问题：“Go 语言到底是传值（值传递），还是传引用（引用传递）” 进行了基本的讲解和分析。

另外在业内中，最多人犯迷糊的就是 slice、map、chan 等类型，都会认为是 “引用传递”，从而认为 Go 语言的 xxx 就是引用传递，我们对此也进行了案例演示。

这实则是不大对的认知，因为：“如果传过去的值是指向内存空间的地址，是可以对这块内存空间做修改的”。

其确实复制了一个副本，但他也借由各手段（其实就是传指针），达到了能修改源数据的效果，是引用类型。

石锤，Go 语言只有值传递，

## 鼓励

若有任何疑问欢迎评论区反馈和交流，**最好的关系是互相成就**，各位的**点赞**就是[煎鱼](https://github.com/eddycjy)创作的最大动力，感谢支持。

> 文章持续更新，可以微信搜【脑子进煎鱼了】阅读，本文 **GitHub** [github.com/eddycjy/blog](https://github.com/eddycjy/blog) 已收录，Go 学习地图，欢迎 Star 催更。


参考
--

*   Go 读者交流群
    
*   When are function parameters passed by value?
    
*   Java 到底是值传递还是引用传递？
    
*   Go语言参数传递是传值还是传引用


================================================
FILE: content/posts/go/var.md
================================================
---
title: "为什么 Go 有两种声明变量的方式，有什么区别，哪种好？"
date: 2022-02-05T15:56:48+08:00
toc: true
images:
tags: 
  - go
---

大家好，我是煎鱼。

有一个读者刚入门 Go ，提了一个很有意思的问题：Go 有几种种声明变量的方式，作为初学者，到底用哪种，有什么区别，又为什么要有多种声明方式呢？

为此，煎鱼将和大家一起探索这个问题。

## 变量声明

在 Go 中，一共有 2 种变量声明的方式，各有不同的使用场景。

分别是：
- 标准变量声明（Variable declarations）。
- 简短变量声明（Short variable declarations）

### 标准声明

变量声明创建了一个或多个变量，为它们绑定了相应的标识符，并给每个变量一个类型和初始值。

使用语法：

```go
VarDecl     = "var" ( VarSpec | "(" { VarSpec ";" } ")" ) .
VarSpec     = IdentifierList ( Type [ "=" ExpressionList ] | "=" ExpressionList ) .
```

案例代码：

```go
var i int
var U, V, W float64
var k = 0
var x, y float32 = -1, -2
var (
	i       int
	u, v, s = 1.0, 2.0, "脑子进煎鱼了"
)
```

### 简短声明

一个短变量声明。使用语法：

```
ShortVarDecl = IdentifierList ":=" ExpressionList .
```

案例代码：

```go
s := "煎鱼进脑子了"
i, j := 0, 10
f := func() int { return 7 }
ch := make(chan int)
r, w, _ := os.Pipe()
_, y, _ := coord(p) 
```

## 网友疑惑

在我们群里的 Go 读者提了这问题后，我也搜了搜相关资料。发现在 stackoverflow 上也有人提出了类似的疑惑：

![](https://files.mdnice.com/user/3610/ff663b2b-d65a-4969-b5bb-03bc81a247b5.png)

问题是：使用哪一种声明方式，令人困惑。

题主纠结的原因在于：
- 如果一个只是另一个的速记方式，为什么它们的行为会不同？
- Go 的作者出于什么考虑，让两种方式来声明一个变量（为什么不把它们合并成一种方式）？只是为了迷惑我们？
- 有没有其他方面需要我在使用时留心的，以防掉进坑里？

下面我们结合 stackoverflow 的这个提问内容和回答，进一步展开。

思考一下：标准声明和短声明，这两者的区别的在哪那里，又或是凭喜好随意使用？



## 区别在哪

### 代码块的分组声明

使用包含关键字 var 的声明语法时，和其他 package、import、const、type、var 等关键字一样，是可以进行分组的代码块声明的。

例如：

```go
var (
	i       int
	u, v, s = 1.0, 2.0, "脑子进煎鱼了"
)
```

而短声明，是不支持的。

### 变量的初始值指定

使用标准的变量定义时，我们可以只声明，不主动地定义该变量的初始值（缺省会给零值）。

例如：

```go
var (
	i    int
	s    string
)
```

而短声明则不行，必须要在程序中主动地去对变量定义一个值。

例如：

```go
s := "脑子进煎鱼了"
```

此处即使是定义的空字符串，那也属于是用户侧主动定义的，而非缺省的零值。

### 局部变量，区分作用域

在编写程序时，我们经常会有一些局部变量声明，且作用域是有限的。

可以看看自己的代码，这种时候，我们都会采取短声明的方式。

例如：

```go
for idx, value := range array {
    // Do something with index and value
}

if num := runtime.NumCPU(); num > 1 {
    fmt.Println("Multicore CPU, cores:", num)
}
```

短声明在这类场景下有明确的优势，标准的变量声明在这类场景不讨好。

### 重新声明变量

在 Go 语言规范中有明确提到，短变量声明是可以重新声明变量的，这是一个高频重新声明的覆盖动作。

如下：

```go
var name = "煎鱼.txt"

fi, err := os.Stat(name)
if err != nil {
    log.Fatal(err)
}

data, err := ioutil.ReadFile(name)
if err != nil {
    log.Fatal(err)
}
...
```

上述代码中，err 变量就是不断地被反复定义。在 `if err != nil` 猖狂的现在，短变量在此处的优势，简直是大杀器了。

## 总结

相信很多小伙伴初入门时都为此纠结过一下，又或是很多教程压根就没有说清楚两者变量声明的区别。

在今天这篇文章中，我们介绍了 Go 的两种变量声明放水。并且针对短声明存在的场景进行了说明。

主要是：
- 代码块的分组声明。
- 变量的初始值指定。
- 局部变量，区分作用域。
- 重新声明变量。

你觉得变量声明上，还有没有别的优缺点呢，欢迎在评论区交流：）

## 参考

- [GoLang Variable Declaration](https://www.tutorialandexample.com/golang-variable-declaration/)
- [Why there are two ways of declaring variables in Go, what's the difference and which to use?](https://stackoverflow.com/questions/27919359/why-there-are-two-ways-of-declaring-variables-in-go-whats-the-difference-and-w)
- [What is the best practice when declaring variables in go (golang)? E.G. should I use "var x int = 1" or just "x := 1"?](https://www.quora.com/What-is-the-best-practice-when-declaring-variables-in-go-golang-E-G-should-I-use-var-x-int-1-or-just-x-1)

================================================
FILE: content/posts/go/when-gc.md
================================================
---
title: "Go 什么时候会触发 GC？"
date: 2021-12-31T12:55:08+08:00
toc: true
images:
tags: 
  - go
  - 面试题
---

大家好，我是煎鱼。

Go 语言作为一门新语言，在早期经常遭到唾弃的就是在垃圾回收（下称：GC）机制中 STW（Stop-The-World）的时间过长。

那么这个时候，我们又会好奇一点，作为 STW 的起始，Go 语言中什么时候才会触发 GC 呢？

今天就由煎鱼带大家一起来学习研讨一轮。

## 什么是 GC

在计算机科学中，垃圾回收（GC）是一种自动管理内存的机制，垃圾回收器会去尝试回收程序不再使用的对象及其占用的内存。

最早 John McCarthy 在 1959 年左右发明了垃圾回收，以简化 Lisp 中的手动内存管理的机制（来自 @wikipedia）。

![图来自网络](https://files.mdnice.com/user/3610/09425faf-f521-43a9-a7fa-1db3c5163914.png)

## 为什么要 GC

手动管理内存挺麻烦，管错或者管漏内存也很糟糕，将会直接导致程序不稳定（持续泄露）甚至直接崩溃。

## GC 触发场景

GC 触发的场景主要分为两大类，分别是：
1. 系统触发：运行时自行根据内置的条件，检查、发现到，则进行 GC 处理，维护整个应用程序的可用性。
2. 手动触发：开发者在业务代码中自行调用 ` runtime.GC` 方法来触发 GC 行为。

### 系统触发

在系统触发的场景中，Go 源码的 `src/runtime/mgc.go` 文件，明确标识了 GC 系统触发的三种场景，分别如下：

```golang
const (
	gcTriggerHeap gcTriggerKind = iota
	gcTriggerTime
	gcTriggerCycle
)
```
- gcTriggerHeap：当所分配的堆大小达到阈值（由控制器计算的触发堆的大小）时，将会触发。
- gcTriggerTime：当距离上一个 GC 周期的时间超过一定时间时，将会触发。
    -时间周期以 `runtime.forcegcperiod` 变量为准，默认 2 分钟。
- gcTriggerCycle：如果没有开启 GC，则启动 GC。
    - 在手动触发的 `runtime.GC` 方法中涉及。

### 手动触发

在手动触发的场景下，Go 语言中仅有 `runtime.GC` 方法可以触发，也就没什么额外的分类的。

![](https://files.mdnice.com/user/3610/8da69a96-6445-4e20-9234-a0c74ba2b5de.png)

但我们要思考的是，一般我们在什么业务场景中，要涉及到手动干涉 GC，强制触发他呢？

需要手动强制触发的场景极其少见，可能会是在某些业务方法执行完后，因其占用了过多的内存，需要人为释放。又或是 debug 程序所需。

## 基本流程

在了解到 Go 语言会触发 GC 的场景后，我们进一步看看触发 GC 的流程代码是怎么样的，我们可以借助手动触发的 `runtime.GC` 方法来作为突破口。

核心代码如下：

```golang
func GC() {
	n := atomic.Load(&work.cycles)
	gcWaitOnMark(n)

	gcStart(gcTrigger{kind: gcTriggerCycle, n: n + 1})
  
	gcWaitOnMark(n + 1)

	for atomic.Load(&work.cycles) == n+1 && sweepone() != ^uintptr(0) {
		sweep.nbgsweep++
		Gosched()
	}
  
	for atomic.Load(&work.cycles) == n+1 && atomic.Load(&mheap_.sweepers) != 0 {
		Gosched()
	}
  
	mp := acquirem()
	cycle := atomic.Load(&work.cycles)
	if cycle == n+1 || (gcphase == _GCmark && cycle == n+2) {
		mProf_PostSweep()
	}
	releasem(mp)
}
```
1. 在开始新的一轮 GC 周期前，需要调用 `gcWaitOnMark` 方法上一轮 GC 的标记结束（含扫描终止、标记、或标记终止等）。
2. 开始新的一轮 GC 周期，调用 `gcStart` 方法触发 GC 行为，开始扫描标记阶段。
3. 需要调用 `gcWaitOnMark` 方法等待，直到当前 GC 周期的扫描、标记、标记终止完成。
4. 需要调用 `sweepone` 方法，扫描未扫除的堆跨度，并持续扫除，保证清理完成。在等待扫除完毕前的阻塞时间，会调用 `Gosched` 让出。
5. 在本轮 GC 已经基本完成后，会调用 `mProf_PostSweep` 方法。以此记录最后一次标记终止时的堆配置文件快照。
6. 结束，释放 M。

## 在哪触发

看完 GC 的基本流程后，我们有了一个基本的了解。但可能又有小伙伴有疑惑了？

本文的标题是 “GC 什么时候会触发 GC”，虽然我们前面知道了触发的时机。但是....Go 是哪里实现的触发的机制，似乎在流程中完全没有看到？

### 监控线程

实质上在 Go 运行时（runtime）初始化时，会启动一个 goroutine，用于处理 GC 机制的相关事项。

代码如下：

```golang
func init() {
	go forcegchelper()
}

func forcegchelper() {
	forcegc.g = getg()
	lockInit(&forcegc.lock, lockRankForcegc)
	for {
		lock(&forcegc.lock)
		if forcegc.idle != 0 {
			throw("forcegc: phase error")
		}
		atomic.Store(&forcegc.idle, 1)
		goparkunlock(&forcegc.lock, waitReasonForceGCIdle, traceEvGoBlock, 1)
    // this goroutine is explicitly resumed by sysmon
		if debug.gctrace > 0 {
			println("GC forced")
		}

		gcStart(gcTrigger{kind: gcTriggerTime, now: nanotime()})
	}
}
```

在这段程序中，需要特别关注的是在 `forcegchelper` 方法中，会调用 `goparkunlock` 方法让该 goroutine 陷入休眠等待状态，以减少不必要的资源开销。

在休眠后，会由 `sysmon` 这一个系统监控线程来进行监控、唤醒等行为：

```golang
func sysmon() {
	...
	for {
		...
		// check if we need to force a GC
		if t := (gcTrigger{kind: gcTriggerTime, now: now}); t.test() && atomic.Load(&forcegc.idle) != 0 {
			lock(&forcegc.lock)
			forcegc.idle = 0
			var list gList
			list.push(forcegc.g)
			injectglist(&list)
			unlock(&forcegc.lock)
		}
		if debug.schedtrace > 0 && lasttrace+int64(debug.schedtrace)*1000000 <= now {
			lasttrace = now
			schedtrace(debug.scheddetail > 0)
		}
		unlock(&sched.sysmonlock)
	}
}
```

这段代码核心的行为就是不断地在 for 循环中，对 `gcTriggerTime` 和 `now` 变量进行比较，判断是否达到一定的时间（默认为 2 分钟）。

若达到意味着满足条件，会将 `forcegc.g` 放到全局队列中接受新的一轮调度，再进行对上面 `forcegchelper` 的唤醒。

### 堆内存申请

在了解定时触发的机制后，另外一个场景就是分配的堆空间的时候，那么我们要看的地方就非常明确了。

那就是运行时申请堆内存的 `mallocgc` 方法。核心代码如下：

```golang
func mallocgc(size uintptr, typ *_type, needzero bool) unsafe.Pointer {
	shouldhelpgc := false
	...
	if size <= maxSmallSize {
		if noscan && size < maxTinySize {
			...
			// Allocate a new maxTinySize block.
			span = c.alloc[tinySpanClass]
			v := nextFreeFast(span)
			if v == 0 {
				v, span, shouldhelpgc = c.nextFree(tinySpanClass)
			}
			...
			spc := makeSpanClass(sizeclass, noscan)
			span = c.alloc[spc]
			v := nextFreeFast(span)
			if v == 0 {
				v, span, shouldhelpgc = c.nextFree(spc)
			}
			...
		}
	} else {
		shouldhelpgc = true
		span = c.allocLarge(size, needzero, noscan)
		...
	}

	if shouldhelpgc {
		if t := (gcTrigger{kind: gcTriggerHeap}); t.test() {
			gcStart(t)
		}
	}

	return x
}
```

- 小对象：如果申请小对象时，发现当前内存空间不存在空闲跨度时，将会需要调用 `nextFree` 方法获取新的可用的对象，可能会触发 GC 行为。
- 大对象：如果申请大于 32k 以上的大对象时，可能会触发 GC 行为。

## 总结

在这篇文章中，我们介绍了 Go 语言触发 GC 的两大类场景，并分别基于大类中的细分场景进行了一一说明。

一般来讲，我们对其了解大概就可以了。若小伙伴们对其内部具体实现感兴趣，也可以以文章中的代码具体再打开看。

但需要注意，很有可能 Go 版本一升级，可能又变了，学思想要紧 ：）


================================================
FILE: content/posts/go-meetup1017.md
================================================
---
title: "快速了解 2020 Gopher Meetup 深圳站"
date: 2020-10-18T01:03:25+08:00
toc: true
images:
tags: 
  - meetup
---

昨天（20201017）很有幸的参加了 GoCN 的 2020 Gopher Meetup 深圳站，在台下听各位大佬分享各自的知识和案例。恰好也是我第一次参加这类 Meetup。因此希望也能够让没来的小伙伴对本次分享内容有一定的了解。

按过往对其观察的惯例，一般在下周后官方就会陆续释出 Meetup PPT 和推文，在此引个主线。

![会场外的展板，图来自 GoCN](https://image.eddycjy.com/08910eccd6b1b0c16c0f60571cd7745a.jpeg)

本次 Meetup 主要的方向是云原生，包含四位讲师分享，分享的主题如下：

1. 华为云的 go 语言云原生实践。
2. go 云上微服务模式解构。
3. 服务网格在边缘计算领域的实践与探索。
4. 腾讯大规模 etcd 集群治理与优化实践。

## 华为云的 go 语言云原生实践

讲述华为云在早起使用 Go 语言时，当时 Go 语言的整体生态圈还比较薄弱，因此很多第三方基础/工具库并不全：

![](https://image.eddycjy.com/4adaf1b0b465a3197a9ba9d714dda51d.jpeg)

围绕此整体做一系列的东西，主要从统一框架开始做，提供各种插件，组件，基本涵盖了常用的所有组件。其所带来的的价值/效益：能够直接提高研发效能，让其他业务能够简单使用，不需要太重复造轮子：

![](https://image.eddycjy.com/8c0afff2cb0bb6d2901d1e4d7f8296f2.jpeg)

再往后就介绍了其使用了 Mesh 去做整块的流量标识，金丝雀等流量控制方案。同时还支持了市面上常见的框架和协议。是一个比较完整很常见的整体解决方案，有真实的参考意义。

若在企业内部有建设过这类基础应用可能会感触比较深，且各家多多少少都有类似的东西，需要必需品。社区的小伙伴可以多看看，结合自己的实际情况进行选型或融合。

同时该类基础规范，最难的可能还是如何在企业内部达到大一统，做推广，拿规范，遵守则。

## go 云上微服务模式解构

详细介绍了云原生的定义，主体讲解了 k8s 的基本网络模型，核心在于传统微服务模式和云原生模式下的各类优缺点和对比。

### Edge Proxy

![](https://image.eddycjy.com/0275954e8196ac7c687a1c58e1b4be23.jpeg)

### ServiceMesh

![](https://image.eddycjy.com/794182e59306fec93128765f1854a353.jpeg)

需要听讲者有一定的基础，整体语速相当快，口述内容也比较多，因此这块没有过多详细记述。

演讲内容主体对应云原生下的几种部署模式，线上的话在网上查阅资料学习即可，可能会更高效些。

印象比较深的是，讲师表述目前也没用 ServiceMesh，四年前也预演过，但问题不少，近期打算重新启动。这块我司也多次尝试，多多少少都有些问题，期待 Istio 更稳定成熟的一天。

## 服务网格在边缘计算领域的实践与探索

主体介绍边缘计算相关的 KubeEdge、IEF 等技术体系：

![](https://image.eddycjy.com/ddab54efbf97b478c4ea06c8a602dcef.jpeg)

这块不是我的技术领域内，隔壁的小哥也没听懂，稍微有些乱，因此不过多的介绍。

但发现讲师刚毕业一年多，年轻有为，潜力无限。

## 腾讯大规模 etcd 集群治理与优化实践

腾讯云近期推出了 etcd 的云服务，先前关注了一番。恰好这次的分享者就是相关人士。

分享内容主要分为两个部分：

1. etcd 本身的基本知识

2. etcd 云服务的介绍

### etcd 知识

第一部分是 etcd 的基本知识，以及抽出 kubectl 查询作为案例进行逻辑分析：

![](https://image.eddycjy.com/515c7ea827f0d19b0cedab48897ddc62.jpeg)

再更一步介绍了 etcd 读请求分析，软件分层，以及一些内部逻辑，流转模型等：

![](https://image.eddycjy.com/fe56478c26fcbcf2b7441e27156f125b.jpeg)

若有兴趣的小伙伴可以结合 PPT 再去追一遍源码，会比较的有意思。

因为其讲述的具体的操作模式涉及了 etcd 里的基本理念，大部分情形下都会展开讨论。

### etcd 云服务

第二部分是讲解腾讯云自身在做 etcd 云服务时，遇到的一些 etcd 自身的 BUG，利用了 Chaos 来制造混沌，以此来更好的发现问题。并在后半部分讲述了 etcd 云服务的大体设计和内部模块结构：

![](https://image.eddycjy.com/f864e44559ea61f3a666ce676bf2d5f3.jpeg)

后半部分感觉比较贴近产品介绍，因为每个模块都能单独拿出来再做一次分享，有限的时间能也很难讲深。

印象最深的还是 “为什么 kubernetes 会选型 etcd？”，讲师给出的答案是：Watch 机制、高可用、商业原因。

各位可以细品一下。

## 总结

整体来讲，个人感觉本次 Meetup 以技术的半解决方案和理念介绍居多。

一个技术的实际应用，普遍分三部分来看：

1. 在价值上：为什么要这么做，做了对公司，对团队，对个人的利弊，外部/内部价值是什么。

2. 在技术上：技术攻坚，这个大家接触的多。

3. 在推广上：，如何规范，推广，是行政命令，还是深抓用户痛点，怎么落的地，是非常重要的。

技术类 Meetup 一般以技术角度居多，因此在与会前，建议提前了解一些基本知识才能在会议上更好的听懂、发散以及思考，否则很难碰撞出火花出来。

但问题又来了，如果已经有了基本知识，肯定会做知识拓展，因此直接网上查阅资料和与业界朋友沟通能达到更佳的目的，更高的时间效率比。因此这是一个矛盾和定位。

其实每一次 Meetup 的背后，组织方和分享讲师其实都会付出大量的精力，都不容易。

抛出一个问题，**如果你是讲师，你怎么在 40-60 分钟内把一份 PPT 讲好？把知识/价值传达到位？**

================================================
FILE: content/posts/go-programming-tour-book.md
================================================
---
title: "新书《Go语言编程之旅：一起用Go做项目》出版啦！"
date: 2020-07-03T21:06:33+08:00
toc: true
tags: 
  - go
---

从我开始写技术文章起，不知不觉近三年过去了，咨询和催我出书和读者逐年递增，在 2019 年算是达到一个高峰。当然，综合考虑下我也是一直拒绝的，觉得火候还不够。

直至 2019.09 月，polaris 主动找到了我，说有事情想找我商量，本着 “如果你在纠结一件事情做还是不做，不如先做了看看结果，至少不会后悔” 的想法，更何况是长期被 Ping，因此我一口答应下来，故事自此开始了。

![image](https://image.eddycjy.com/04737f7b3e5567224fd2bc93f352203d.jpeg)

## 本书定位

本书不直接介绍 Go 语言的语法基础，内容将面向项目实践，同时会针对核心细节进行分析。而在实际项目迭代中，常常会出现或多或少的事故，因此本书也针对 Go 语言的大杀器（分析工具）以及常见问题进行了全面讲解。

本书适合已经大致学习了 Go 语言的基础语法后，想要跨越到下一个阶段的开发人员，可以填补该阶段的空白和进一步拓展你的思维方向。

## 读者定位

- 基本了解 Go 语言的语法和使用方式的开发人员。
- 想要进行 Go 相关项目实践和进一步摸索的开发人员。
- 希望熟悉 Go 常用分析工具的开发人员。

## 本书大纲

本书针对常见的项目类型，主要细分为 5 + 1 板块，分别是命令行、HTTP、RPC、Websocket 应用、进程内缓存以及 Go 中的大杀器。

同时我们在项目开发、细节分析、运行时分析等方方面面都进行了较深入的介绍和说明，能够为 Go 语言开发者提供相对完整的项目实践经验，而如果深入阅读第六章的章节，更能够为未来各类问题出现时的问题排查提供一份强大的知识板块。

如下为本书的思维导图概览：

![image](https://image.eddycjy.com/e5eafb17140fdc06830b838eb7fb0468.png)

## 如何阅读这本书

常规的列目录未免太无趣。我想不如说说从我个人的角度，所看到读者们在近 3 年来是如何阅读/实践我的实践系列文章的，其面向的读者群体是完全一致的。希望能够从另外一个角度告诉你，应当如何阅读这本书，尽可能的效益最大化。

首先，图书，买来要读，而与实战结合的图书，势必需要实践，实践最常见又分为脑内思考和上机实践：

![image](https://image.eddycjy.com/a6faa89061d62be755b715607e2563b8.jpg)

而在持续的交流中，可以发现至少会延伸出以下几类深入层次的不同：

![image](https://image.eddycjy.com/e3b17b0867e66bda4b5c6fb24ddcebc9.jpg)

- **第一层**：只阅读，留有印象，需要时再唤醒，也行。

- **第二层**：阅读并实践，实打实的完成项目实践，收获丰满。

- **第三层**：实践的过程中，**一定会遇到或大或小的问题**，有的人会放弃，这就是分叉点。但有的读者会持续排查，其提升了个人能力（排错能力很重要）。

- **第四层**：实践完毕后，有自己的想法，认为某某地方还可以这样，也可以再实现更多的功能，举一反三，进一步拓展，并对项目提 issues 或进行 pr。

- **第五层**：完成整体项目后，抽离业务代码，标准化框架，实现框架的应用脚手架，并有的读者会进一步开源。

- **第六层**：形成脚手架后，在自己业务组开始落地，实际在项目中使用，由业务学习转化为企业实践。

- **第七层**：在内部落地实践稳妥后，开始在其它业务组开始推广该框架脚手架，进一步标准化，拓展思路。

通过上图中 “七层金字塔” 的理解，我们不难发现其对于实践项目的理解和应用已经不再是单单这个项目，而是有了更深远的意义，抽象一下，对照着著名的 “学习效率金字塔” 来看：

![image](https://image.eddycjy.com/a35394d0ab562efaac8367c3eeff4b07.jpg)

在单纯的 “阅读” 时，其基本处于 “被动学习” 的阶段，而单进入阅读并实践时，已经转为了 “主动学习”，且绝大部分的读者做完实践后，表示 “嗯，实践完，挺好的，有所得”。

这时候就会进入到一个新的阶段（分叉点），绝大部分读者在做完后，会纠结 ”接下来要做什么“：

![image](https://image.eddycjy.com/16c678d883fe3b4e1db5fa99dfd0b302.jpg)

有部分读者会停滞，也有部分读者会转入 “转教别人/立即应用” 的阶段，也就是普遍的在企业内部进行标准化的使用，又或是开源项目，据此得到更一步的深入实践和提高，更大的吸收差距也在于此。

当然，这一切都要基于前面的 “1”，你得先买了书，读了书，接着就是你的选择和创建机遇的能力了，不同的路线效益自然不一样。

## 广告时间

在《Go语言编程之旅：一起用Go做项目》写作中后期，作为 2020 年的煎鱼，我回顾了 2018、2019 年的煎鱼所写的文章，在现在看来发现多多少少都有些瑕疵。再对比本书，在同类主题下，写出的内容更具知识结构化和实战意义，且能做出更优的选题抉择，确实变化了。

因此我也在这里正式向你推荐本书，希望能够给所有 Go 语言爱好者带来更大的技术价值和切切实实的项目实践经验。

后续有任何问题或建议也欢迎随时来交流。

![image](https://image.eddycjy.com/2b7e6446c9eaeeef1658b595bd58512a.jpeg)

## 关于写书

有关注我的小伙伴应该会发现，我之前突然退了很多个微信群，并且停止了博客的更新，也较少在社区里冒泡了。其实本质上是为了给写书让路，希望尽可能的把业余时间都聚焦在写书上。

这时候又会有另外一个问题，那就是写书，是一件非常长耗时的事情，没有任何的外界反馈，因此我严格做了一系列的 todolist 和时间节点的管理，围绕着自己的生活作息设置了一系列闹钟作为信号量提醒自己。

基本是吃饭、睡前构思结构、想灵感，下班回到家一坐下就开始写内容。当然，我也经常走火入魔一想到好的灵感就激动的掏出手机记在工具上，免得第二天大脑重置后丢失了数据，那就很可惜。

最终在长期的坚持下自然而然也就完成了这本书的写作。

## 感谢你们

非常感谢 polaris，在艰难的情况下依旧完成了本书的编写。感谢博文视点的编辑安娜，基本从不催更。感谢曹大、无闻、杨文、傲飞、大彬、晓东的推荐词或 Review.

我还记得当时曹大的书出版时，因为种种原因，我还立下过 ”绝不写书” 的 flag，和晓东在深圳湾一号吃自助餐时立过 “绝对不会放弃，一定会写完” 的 flag，果然计划赶不上变化，flag 该折折。

当然，最该感谢的还是我司的研发负责人，当年把我从个小角落里筛了出来，否则也不会有这一切的开端了。

================================================
FILE: content/posts/kubernetes/2020-05-01-install.md
================================================
---
title: "Kubernetes 本地快速启动（基于 Docker）"
date: 2020-05-01T11:25:52+08:00
toc: true
tags: 
  - kubernetes
---

Kubernetes 在容器编排大战结束后已经在云原生中占据了明确的一席，最近几年越来越火热，目前搜索趋势：

![image](https://image.eddycjy.com/2583d073cc05df561c735564bb3e9e81.jpg)

Kubernetes 的热度很明显是不断地在上涨，因此学习和使用 Kubernetes 是一件相对正确的事，同时公司大多都在往容器化上接近，在拥抱 Kubernetes，所以我们所开发的应用也总是跑在容器环境中。更甚的是，需要对接 Kubernetes API 来做一些功能的开发。

这个时候，我们就需要一个 Kubernetes 环境来进行开发和调试，但你准备开始时，又遇到了一个问题，虽然在 2020 年的现在，Kubernetes 的安装已经有了极大的简化，教程也满地跑，但 Kubernetes 的安装和运行依然有一定的要求，像我，就遇到了如下问题：

![image](https://image.eddycjy.com/9ee9dd19241bfc9099603abcc455787d.jpg)

显然，我的小水管 Mac 承受不起，但是又需要对 Kubernetes 进行学习和使用，除了买云服务器，又或是再在台式机上搭虚拟机，还有没有什么办法呢。

非运维开发的情况下，入门级中最简单的方式就是采用 Docker 所提供的 Kubernetes 支持。

## Docker for Mac/Windows with Kubernetes

Docker 在 17.12.ce 起就提供了 Mac 版本的 [Kubernetes Beta](https://www.docker.com/blog/docker-mac-kubernetes/) 支持，在初始使用上来说非常的方便。首先我们检查 Docker 的版本，点击 Docker -> Check for Updates 确保你的 Docker 在最新版本。

## 快速安装 Kubernetes

在升级完成后，我们可以点击 Docker -> Preferences -> Kubernetes，如下图：

![image](https://image.eddycjy.com/85e953f790c6b6955aa307445a8cf67a.jpg)

你会发现存在三个选项，分别是：Enable Kubernete、Deploy Docker Stacks to Kubernetes by default、Show system containers (advanced)。

一般我们只勾选 “Enable Kubernetes” 选项，如果你还想通过 `docker ps` 查看到 Kubernetes 的相关容器信息，那么还可以勾选 “Show system containers” 选项，在勾选完毕后点击右下角的 “Apply” 按钮就可以了。

这个时候 Docker Preferences 界面上的 Kubernetes 选项将会进入 `kubernetes is starting...` 状态，也就是在拉取各类镜像，需要一定的时间。

这一步有一点需要注意，Kubernetes 大多数的镜像都在国外，如果不翻墙你是无法正常下载的，就会导致一直阻塞在 `kubernetes is starting...`，等半天也没有响应，这种情况下你可以把镜像源改为国内，又或是参考 [k8s-docker-desktop-for-mac](https://github.com/gotok8s/k8s-docker-desktop-for-mac) 项目来安装。

最后在安装完毕后，你可以检查 Docker Preferences 界面左下角的 Kubernetes 状态是否正常就可以了，如下图：

![image](https://image.eddycjy.com/2e626b97af3549deff1f693800bd1275.jpg)

## 安装 Dashboard

在完成 Kubernetes 的安装后，我们需要安装 Dashboard，执行如下命令：

```bash
$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/dashboard/v1.10.1/src/deploy/recommended/kubernetes-dashboard.yaml
```

该 Dashboard 对应 [kubernetes/dashboard](https://github.com/kubernetes/dashboard) 项目，而所选择的版本号（兼容性问题），大家可以根据 Releases 中的 Compatibility 来进行选择，但一般不需要太在意，因为 Kubernetes 在 Dashboard 上的建设重心已经逐渐偏向 Promethues 体系了，因此在这一块是比较滞后的，如果想特别依赖 Dashboard 来进行分析，也可以自行选择一些成熟的开源产品。

在完成 `apply` 后，进行代理，执行如下命令：

```
// 默认 8001 端口，若有需要可通过 --port=8080 进行指定
$ kubectl proxy
```

执行完毕完毕后，我们可以直接在通过浏览器访问 `http://localhost:8001/api/v1/namespaces/kube-system/services/https:kubernetes-dashboard:/proxy/#!/login` 地址，如下图：

![image](https://image.eddycjy.com/905246b8d5150f90282b2b56eaf6a5c8.jpg)

## 创建 ServiceAccount

我们在本地创建一个 k8s-admin.yaml 文件，创建一个 ServiceAccount 和角色绑定关系，写入如下文件内容：

```
apiVersion: v1
kind: ServiceAccount
metadata:
  name: dashboard-admin
  namespace: kube-system
---
kind: ClusterRoleBinding
apiVersion: rbac.authorization.k8s.io/v1beta1
metadata:
  name: dashboard-admin
subjects:
  - kind: ServiceAccount
    name: dashboard-admin
    namespace: kube-system
roleRef:
  kind: ClusterRole
  name: cluster-admin
  apiGroup: rbac.authorization.k8s.io
```

获取管理员角色的 `secret` 名称：

```
$ kubectl get secrets -n kube-system | grep dashboard-admin | awk '{print $1}'
dashboard-admin-token-dknqx
```

获取对应的管理员的 `token` 值：

```
$ kubectl describe secret dashboard-admin-token-dknqx -n kube-system
Name:         dashboard-admin-token-dknqx
Namespace:    kube-system
Labels:       <none>
Annotations:  kubernetes.io/service-account.name: dashboard-admin
              kubernetes.io/service-account.uid: 2f817ddd-5802-4e8b-8c38-f4affc16a6fe

Type:  kubernetes.io/service-account-token

Data
====
ca.crt:     1025 bytes
namespace:  11 bytes
token:      eyJhbGciOiJSUzI1NiIsImtpZCI6IiJ9.eyJpc3MiOiJrdWJlcm5ldGVzL3NlcnZpY2VhY2NvdW50Iiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9uYW1lc3BhY2UiOiJrdWJlLXN5c3RlbSIsImt1YmVybmV0ZXMuaW8vc2VydmljZWFjY291bnQvc2VjcmV0Lm5hbWUiOiJkYXNoYm9hcmQtYWRtaW4tdG9rZW4tZGtucXgiLCJrdWJlcm5ldGVzLmlvL3NlcnZpY2VhY2NvdW50L3NlcnZpY2UtYWNjb3VudC5uYW1lIjoiZGFzaGJvYXJkLWFkbWluIiwia3ViZXJuZXRlcy5pby9zZXJ2aWNlYWNjb3VudC9zZXJ2aWNlLWFjY291bnQudWlkIjoiMmY4MTdkZGQtNTgwMi00ZThiLThjMzgtZjRhZmZjMTZhNmZlIiwic3ViIjoic3lzdGVtOnNlcnZpY2VhY2NvdW50Omt1YmUtc3lzdGVtOmRhc2hib2FyZC1hZG1pbiJ9.NKa8OESUsvrolyxezo8w_auKr7jC94gmCm2ZyvQda5X1wOImYYqnH482sDPsQ5Y_V-RH2UD-4eBIuZP6gh0p50nxz-gPqEEPdRln_7osbRMCgcGzqajVo3bx7UOLTJC9ka9S-0rv5HYbn3yeVi6Pt4sVW5GF6KInDcbyyYgse5B_nySIpw4AjdWXNG0npLjneBCQWrVKAQSYYw2mLPZAPPjw6yjXnBvqZmtH1wyvCsKAXbZqBtTp7ddIVvtmveeBuELsX5yIzWqD7qhcpZz4v07FrsfqK0_QJ18BBDBGYMJaaoaK0h2pl_E9sIlAXoBCJ6ol_wwUzfuOshPo9adqww
```

如果已经熟悉了，可以直接通过组合命令直接获取 token 值：

```
$ kubectl describe secret dashboard-admin-token-dknqx -n kube-system | grep -E '^token' | awk '{print $2}'
```

## 登陆 Dashboard

最后我们将 `token` 保存并复制到 Kubernetes Dashboard 的仪表盘并登陆，我们就可以看到如下界面：

![image](https://image.eddycjy.com/980b8975a010b6321de4e87cb29fb009.jpg)

## 小结

我们又回到最初的问题，要学习和使用 Kubernetes，最快最正确的方式，那就是尽快的进行实践，因为本质上我们不是运维开发人员，部署环境的 Kubernetes 也大多不是由你亲自搭建，因为中小微会直接用某云厂商的 Kubernetes，大厂有专职的人员，也不愁这个问题。

因此尽快行动，完成迭代中的需求是我们的目的，等完成后，再回过头来一步步手动搭建 Kubernetes 也未尝不可，所以我认为 Docker for Mac/Windows with Kubernetes 在初级入门阶段是一个很好的安装和使用方法。


================================================
FILE: content/posts/kubernetes/2020-05-03-deployment.md
================================================
---
title: "在 Kubernetes 中部署应用程序"
date: 2020-05-03T11:05:00+08:00
toc: true
tags: 
  - kubernetes
---

在完成了本地 Kubernetes 的快速搭建（基于 Docker）后，我们已经可以正式的使用它了。对于我们平时最常见的需求，那就是往 Kubernetes 里部署应用程序，如果你没有看过 Kubernetes 相关的知识，这时候你可能会六神无主，但问题不大，我们就可以使用最经典的 Nginx 来小试身手。


## 创建 Deployment

创建 nginx-deployment.yaml 文件：

```yaml
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  labels:
    app: nginx
spec:
  replicas: 2
  selector:
    matchLabels:
      app: nginx
  template:
    metadata:
      labels:
        app: nginx
    spec:
      containers:
      - name: nginx
        image: nginx:1.18.0
```

应用 nginx-deployment.yaml 文件：

```shell
$ kubectl apply -f nginx-deployment.yaml
deployment.apps/nginx-deployment created
```

## 查看运行状态

查看 Pod 运行情况：

```shell
$ kubectl get pods
NAME                               READY   STATUS    RESTARTS   AGE
nginx-deployment-9fbc65d67-9j68x   1/1     Running   0          1m
nginx-deployment-9fbc65d67-nwbhj   1/1     Running   0          1m
```

查看 Deployment 部署情况：

```shell
$ kubectl get deployment
NAME               READY   UP-TO-DATE   AVAILABLE   AGE
nginx-deployment   2/2     2            2           29m
```

我们也可以通过 describe 命令进行查看

```shell
$ kubectl describe pod nginx-deployment-9fbc65d67-9j68x
Name:           nginx-deployment-9fbc65d67-9j68x
Namespace:      default
Priority:       0
Node:           docker-desktop/192.168.65.3
Start Time:     Fri, 01 May 2020 17:36:12 +0800
Labels:         app=nginx
                pod-template-hash=9fbc65d67
...
Events:
  Type    Reason     Age   From                     Message
  ----    ------     ----  ----                     -------
  Normal  Scheduled  45m   default-scheduler        Successfully assigned default/nginx-deployment-9fbc65d67-9j68x to docker-desktop
  Normal  Pulling    45m   kubelet, docker-desktop  Pulling image "nginx:1.18.0"
  Normal  Pulled     44m   kubelet, docker-desktop  Successfully pulled image "nginx:1.18.0"
  Normal  Created    44m   kubelet, docker-desktop  Created container nginx
  Normal  Started    44m   kubelet, docker-desktop  Started container nginx
```

## 查看 Dashboard

在应用了 Nginx 的 Deployment 后，我们可以查看上一章节中我们所搭建的 Dashboard：

![image](https://image.eddycjy.com/8e08a407d9333759e99a5f09f18e6e8c.jpg)

可能你在想，我只是执行了一条命令，怎么就把 Nginx 跑起来了，这时候你可以去查看容器组中的事件，就能够看到这个容器在运行时做涉及到的事件：

![image](https://image.eddycjy.com/8d96979504a96c5d5b60fad3eeb35060.jpg)

## 部署 Nginx

### 创建 Nginx Service

```shell
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    app: nginx
spec:
  selector:
    app: nginx
  ports:
  - name: nginx-port
    protocol: TCP
    port: 80
```

应用 nginx-service.yaml 文件：

```shell
$ kubectl apply -f nginx-service.yaml
```

查看应用的运行情况：

```shell
$ kubectl get services -o wide
```

但这时候是无法访问到 Nginx 的，我们可以通过 Kubernetes 的 NodePort 的方式对外提供访问：


```
apiVersion: v1
kind: Service
metadata:
  name: nginx-service
  labels:
    app: nginx
spec:
  selector:
    app: nginx
  ports:
  - name: nginx-port
    protocol: TCP
    port: 80
    nodePort: 30001
    targetPort: 80
  type: NodePort
```

然后再进行访问：

```shell
$ curl http://127.0.0.1:30001
<!DOCTYPE html>
<html>
<head>
<title>Welcome to nginx!</title>
...


```

至此我们已经打通了和 Nginx 之间的访问。

## 部署 Go 程序

在部署环境中常常需要将应用程序部署上去，然后对外进行提供服务，我们模拟一个 Go 程序：

```go
func main() {
    r := gin.Default()
    r.GET("/ping", func(c *gin.Context) {
        c.String(http.StatusOK, "pong")
    })
    err := r.Run(":9001")
    if err != nil {
        log.Fatalf("r.Run err: %v", err)
    }
}
```

### 编写和编译 Dockerfile

在项目根目录创建 Dockerfile 文件，进行编写：

```shell
FROM golang:latest

ENV GOPROXY https://goproxy.cn,direct
WORKDIR $GOPATH/src/github.com/eddycjy/awesome-project
COPY . $GOPATH/src/github.com/eddycjy/awesome-project
RUN go build .

EXPOSE 8000
ENTRYPOINT ["./awesome-project"]
```

编译并打标签：

```shell
$ docker build -t eddycjy/awesome-project:v0.0.1 .
...
Successfully built b53cef4d2967
Successfully tagged eddycjy/awesome-project:v0.0.1
```

验证打包进 Docker 中的程序是否正常运行：

```shell
$ docker run -p 10001:9001 awesome-project
[GIN-debug] GET    /ping                     --> main.main.func1 (3 handlers)
[GIN-debug] Listening and serving HTTP on :9001
[GIN] 2020/05/03 - 01:51:40 | 200 |        16.9µs |      172.17.0.1 | GET      "/ping"
```

### 上传到 Dockerhub

登陆并推送镜像到 Dockerhub：

```shell
$ docker login  
$ docker push eddycjy/awesome-project:v0.0.1      
The push refers to repository [docker.io/eddycjy/awesome-project]
8192ac09ffeb: Pushed 
9eb17b90d619: Pushed 
b04d698ea69d: Pushed 
31561785c3fc: Mounted from library/golang 
4486631650dc: Mounted from library/golang 
5e28718a7d23: Mounted from library/golang 
ea1227feeccb: Mounted from library/golang 
9cae1895156d: Mounted from library/golang 
52dba9daa22c: Mounted from library/golang 
78c1b9419976: Mounted from library/golang 
v0.0.1: digest: sha256:a1ef61e899db75eb2171652356be15559f1991b94a971306fb79ceccea8dd515 size: 2422
```

这时候你在 hub.docker.com 上就能看的你刚刚所上传的镜像内容：

![image](https://image.eddycjy.com/605dca784a33f0466c655d4418818154.jpg)

## 编写 Kubernetes 配置

接下来我们需要针对刚刚所打包的 Go 程序创建 Deployment，编写 go-deployment.yaml 文件：

```shell
apiVersion: extensions/v1beta1
kind: Deployment
metadata:
  name: awesome-project
  labels:
    app: awesome-project
spec:
  replicas: 2
  selector:
    matchLabels:
      app: awesome-project
  template:
    metadata:
      labels:
        app: awesome-project
    spec:
      containers:
      - name: awesome-project
        image: eddycjy/awesome-project:v0.0.1
```

创建 Service，编写 go-service.yaml：

```
apiVersion: v1
kind: Service
metadata:
  name: awesome-project-svc
  labels:
    app: awesome-project
spec:
  ports:
  - port: 9001
  type: ClusterIP
  selector:
    app: awesome-project
```

## 部署 Ingress

### Ingress Controller

我们采用 Docker for Mac 特定提供的 Ingress Controller 部署脚本：

```
$ kubectl apply -f https://raw.githubusercontent.com/kubernetes/ingress-nginx/controller-0.32.0/deploy/static/provider/cloud/deploy.yaml
```

其会所有命名空间监视 Ingress 对象，并配置 RBAC 权限，否则你有可能会遇到 403 Forbidden 的问题。

### Nginx Ingress

在完成了 Ingress Controller 等相关部署后，我们可以正式的部署属于自己业务的 Nginx Ingress 对象：

```
apiVersion: extensions/v1beta1
kind: Ingress
metadata:
  name: test-ingress
  annotations:
    nginx.ingress.kubernetes.io/use-regex: "true"
spec:
  rules:
  - host: website-ingress.local
    http:
      paths:
      - backend:
          serviceName: awesome-project-svc
          servicePort: 9001
```

`kubectl apply -f` 应用刚刚所编写的配置文件，然后查看运行情况：

```
$ kubectl get ingresses.
NAME           HOSTS                   ADDRESS     PORTS   AGE
test-ingress   website-ingress.local   localhost   80      8h
```

如何发现 ADDRESS 为空，则存在问题，需要进行排查（可能性有很多）。在确定 ADDRESS 属性正常后，我们需要打开 `/etc/hosts` 并配置 HOST `127.0.0.1 awesome-project.local` ，并进行验证：

```shell
$ curl http://awesome-project.local/ping
pong
```

至此，我们完成了一个简单的 Go 程序的部署和外部调用。

## 小结

在本章中，我们通过部署 Nginx、Ingress、Go 程序的方式，直接实践了 Kubernetes 的基本流程，达到了将自己的简单程序部署在 Kubernetes 的一个小目标，接下来在后续的章节中我们将进一步针对文中所使用到的相关属性和内容进行详细说明。

毕竟在实践过后，就要去了解为什么，这样子才能做到融会贯通。


================================================
FILE: content/posts/kubernetes/2020-05-10-api.md
================================================
---
title: "使用 Go 程序调用 Kubernetes API"
date: 2020-05-10T21:20:26+08:00
toc: true
tags: 
  - kubernetes
---

在前面的章节中，我们介绍了快速部署 Kubernetes 和应用程序的方法，接下来在本章节中我们将对 Kubernetes 的 API 进行了解，并且进行调用，这是开发人员最关注的一环之一。

因为不论是 DevOps、基础架构，又或是自愈，都需要与 Kubernetes API 直接/间接接触，因此即使在你不懂 Kubernetes 的情况下，Kubernetes API 的知识点仍然属于必知必会，API 总得会调。

## 查看 Kubernetes API

### kube-apiserver 架构图

![image](https://d33wubrfki0l68.cloudfront.net/7016517375d10c702489167e704dcb99e570df85/7bb53/images/docs/components-of-kubernetes.png)

（图来自 kubernetes.io）

在 Kubernetes 的架构中，由 kube-apiserver 组件在主节点上提供 Kubernetes API 服务，kube-apiserver 是 Kubernetes 所有控制的前端，对外提供大量的 RESTful API。

最常见的就是 kubelet 命令，实际上也是在调用 kube-apiserver 所提供的的 API。

###  访问 API 和查看列表

在了解 Kubernetes 的基本架构和提供 API 的方式后，接下来我们需要知道 Kubernetes 到底提供了哪些 API。为了方便调试，首先我们需要在本地运行 `kubectl proxy` 命令，kube-apiserver 就会在本地的 8001 端口上进行监听，也就是提供了一个 Kubernetes API 服务的 HTTP 代理。

这个时候我们可以访问：

```shell
$ curl http://localhost:8001/api/v1/
```

查看所提供的对应 API‘s：

```shell
{
  "kind": "APIResourceList",
  "groupVersion": "v1",
  "resources": [
    {
      "name": "bindings",
      "singularName": "",
      "namespaced": true,
      "kind": "Binding",
      "verbs": [
        "create"
      ]
    },
    {
      "name": "componentstatuses",
      "singularName": "",
      "namespaced": false,
      "kind": "ComponentStatus",
      "verbs": [
        "get",
        "list"
      ],
      "shortNames": [
        "cs"
      ]
    },
    ...
  ]
}
```

访问 `api/v1/pods` 路径，获取所有 Pods
```shell
$ curl http://127.0.0.1:8001/api/v1/pods
```

访问结果：

```
{
  "kind": "PodList",
  "apiVersion": "v1",
  "metadata": {
    "selfLink": "/api/v1/pods",
    "resourceVersion": "614376"
  },
  "items": [
    {
      "metadata": {
        "name": "awesome-project-76788db95b-7ztwr",
        "generateName": "awesome-project-76788db95b-",
        "namespace": "default",
        "selfLink": "/api/v1/namespaces/default/pods/awesome-project-76788db95b-7ztwr",
        "uid": "4fdb6661-edbd-4fc6-bf71-1d2dadb3ffc1",
        "resourceVersion": "608545",
        "creationTimestamp": "2020-05-03T02:29:32Z",
        "labels": {
          "app": "awesome-project",
          "pod-template-hash": "76788db95b"
        },
        ...
        ]
      },
    ]
```

更多的 API 列表和介绍可查看[官方文档](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.15/)。

## Go 程序调用 Kubernetes API

接下来进入在本章的重点，也就是在程序中调用 Kubernetes API，Kubernetes 官方提供了 Go 语言的 Client SDK，也就是[kubernetes/client-go](https://github.com/kubernetes/client-go)，我们借助上一章节的 Go 程序，对其进行改造。

### Demo

首先写入如下方法：

```go
func NewK8sInCluster() error {
  config, err := rest.InClusterConfig()
  if err != nil {
    return err
  }

  k8sClient, err = kubernetes.NewForConfig(config)
  if err != nil {
    return err
  }

  return nil
}
```

编写获取 K8S Pod 列表的方法：

```go
func GetPodList(pod Pod) ([]v1.Pod, error) {
  podList, err := k8sClient.CoreV1().Pods(pod.Namespace).List(metav1.ListOptions{})
  if err != nil {
    return nil, err
  }
  pods := podList.Items

  if pod.Name != "" {
    filterPods := make([]v1.Pod, 0, len(pods))
    for _, p := range pods {
      if strings.HasPrefix(p.Name, pod.Name) {
        filterPods = append(filterPods, p)
      }
    }
    pods = filterPods
  }

  return pods, nil
}
```

修改 main 方法中的路由：

```go
func main() {
  r := gin.Default()
  r.GET("/ping", func(c *gin.Context) {
    c.String(http.StatusOK, "pong")
  })
  r.GET("/k8s/pods", func(c *gin.Context) {
    err := NewK8sInCluster()
    if err != nil {
      c.String(http.StatusInternalServerError, "NewK8sInCluster err: %v", err)
    }
    pods, err := GetPodList(Pod{Namespace: "default"})
    if err != nil {
      c.String(http.StatusInternalServerError, "GetPodList err: %v", err)
    }

    c.JSON(http.StatusOK, pods)
  })
  err := r.Run(":9001")
  if err != nil {
    log.Fatalf("r.Run err: %v", err)
  }
}
```

在确定程序正常后，我们重新编译并打标签：

```
$ docker build -t eddycjy/awesome-project:v0.0.2 .
$ docker login  
$ docker push eddycjy/awesome-project:v0.0.2
```

### 部署并验证

修改 go-deployment.yaml 文件：

```
      containers:
      - name: awesome-project
        image: eddycjy/awesome-project:v0.0.2
```

将其应用到 Kubernetes：

```
$ kubectl apply -f go-deployment.yaml 
deployment.extensions/awesome-project configured
```

访问刚刚所编写的接口，如下：

```
$ curl http://website-ingress.local/k8s/pods
[{"metadata":{"name":"awesome-project-64979bcbd9-rm957","generateName":"awesome-project-64979bcbd9-","namespace":"default","selfLink":"/api/v1/namespaces/default/pods/awesome-project-64979bcbd9-rm957","uid":"b0a83787-c547-4d74-9bc4-c930b2188e84","resourceVersion":"...
```


================================================
FILE: content/posts/microservice/dismantle.md
================================================
---
title: "微服务的战争：按什么维度拆分服务"
date: 2020-08-19T20:56:55+08:00
images:
toc: true
tags: 
  - 微服务
---

> “微服务的战争” 是一个关于微服务设计思考的系列题材，主要是针对在微服务化后所出现的一些矛盾/冲突点，不涉及具体某一个知识点深入。如果你有任何问题或建议，欢迎随时交流。

微服务，这三个字正在席卷着目前的互联网软件行业，尤其在近几年云原生迸发后，似乎人人都对微服务有了更广泛的使用和理解，张口就是各种各样的问号，有着强大的好奇心。

无独有偶，我有一个朋友鲤鱼在内部微服务的早期（每个业务组起步）就经常遇到下述的对话：

1. **张三**：为什么要拆现在的代码？

2. **鲤鱼**：因为 ！@*）&&#@*！）&#！&）@！&！ 的原因。

3. **张三**：那即将要做的 “微服务” 是按照什么维度去拆分的服务？

4. **鲤鱼**：常见的一般根据 ！@#*@！#&！（@&！@）#@ 的方式来拆分。

5. **张三**：照你这么说好像也不大对，我看每个业务组拆分的维度似乎都不大一样？

6. **鲤鱼**：嗯，每个业务组还有自己的见解，不会完全相同。

7. **张三**：。。。所以微服务的拆分维度到底是什么？

## 为什么想拆

为什么张三会有这个疑问呢，实际上是因为研发内部希望从原先的大单体，大仓库向微服务体系拆分转换，其原先大单体仓库结构，类 Monorepo：

![image](https://image.eddycjy.com/b61faf600a2648ecce258abfa7d57ce8.jpg)

但类 Monorepo 又有不少的问题，像是：

1. **单个 Repo 体积过大**：导致 Git 无法直接拉取。当你设置完再拉取时，在网速慢时还能去泡杯咖啡，并且在开发机性能不佳的情况下，IDE 会比较卡，代码运行起来也慢。

2. **单个 Repo 存在公共函数/SDK**：在代码仓库中，必然存在公共依赖。因此在解决代码冲突时，若遗留了冲突符，且在动态语言中，不涉及便运行正常。但其实在上线后却又影响到其他业务，可真是糟糕透顶，分分钟被迫抱着事故。

3. **单个 Repo 模块职责/边界不清**：在实际的软件开发中，涉及数十个业务组同时在一个大 Repo 下进行开发，没有强控边界的情况下，往往会逐渐模糊，即使在设计时管得住自己，你也不一定能 100% 防止别人模糊你的边界。

4. **单个 Repo 包含了所有的源码**：出现公司源代码泄露时，会导致整个 Repo 外泄，相当的刺激和具有教育意义。因为虽然开放和协同了，不属于你们组的业务代码你也有权限查看了。

当然，Monorepo 是否又完全不可行呢？实际上国外 Google，Facebook，Twitter 等公司都有在使用 Monorepo，并取得了一定的收益。

其实做 Monorepo 是需要相应的大量工具支撑，若单纯只是一个 Repo 塞多个模块，基本都做不好，甚至引火烧身。还不如早早拆开，至少能确保各业务线服务的相对独立性。

## 拆成什么样

张三在明白了拆的原因后，就出现了第二个问题，那就是 “微服务” 要按照什么样的维度去拆分服务？

张三公司内部对于这块的知识处于模糊不清的阶段，因此需要进行深入了解，便于后续的团队共识和方法论建立，理所当然，十万个为什么也就出现了。

### 大单体变独立服务

最常见的拆分的方式是按照业务模块进行服务的拆解，像是前文所提到的业务模块，在设计上边界非常清晰，这种情况直接拆成各个服务就可以了：

![image](https://image.eddycjy.com/9fe68c7e07a732686240243376da5fcb.jpg)

而在拆分后，又会遇到一个新的问题，也就是张三问第三个问题 “每个业务组拆分的维度似乎都不大一样？”。

因为在实际的执行过程中，严谨一些会由 SM 与 RD 一同开会探讨/规范初版的服务划分，而在持续的快速的迭代中，往往新服务的拆分都是由一线 RD 亲自操刀。

即使是架构师亲自操刀，在相对复杂的业务模型下，不同架构师划分出来的也有可能不完全一致，因此无论是哪种情况，你都会发现每个业务组拆分的维度多多少少都不一样了，毕竟人与人的思想都是不一样的，一千个人有一个千个哈姆雷特，因此张三的疑惑是正常的。

就像下图，核心是定义一只鱼，在不同人的眼中能演化出各种奇奇怪怪的鱼：

![image](https://image.eddycjy.com/53ba3e13d2d58affbd3ee75ea622e7d3.jpg)

### 大数据库变独立数据库

在以前早期的大单体快速迭代中，往往是一个大数据库包含所有的业务数据库（甚至数据库账号都不分），这种时候就会带来各种问题。

像是某一天，你所负责的业务模块数据库莫名其妙出现了一些奇奇怪怪的值，你可能就要抓破脑袋去各种代码和 binlog 查了。更甚还有被网络攻击后，数据库配置被获取，直接跳板一拖直接整个脱裤，那可是糟糕透顶了。

![image](https://image.eddycjy.com/8f3e30b271d218c946dbed5acbd1be5a.jpg)

因此在常见的应用设计中，应用程序在连接数据库时会指定连接特定的域名（例如：eddycjy-user），方便未来迁移。并且每个业务服务分别给予独立的数据库只读权限，进行软隔离。而在业务量上来后，也会对业务数据库进行硬隔离，分配特定的 RDS 实例，就不会互相影响了。

### 环境隔离，独立

在服务拆分后，大多会采取独立部署的方式，将两者之间的环境隔离开来，互不干扰，互不影响：

![image](https://image.eddycjy.com/9bf89f92f766e60c48860cd23439fc75.jpg)

像在云原生中，常见于在 Kubernetes 将一个业务服务作为一个 Service 部署发布，再根据实际的资源和调度情况进行 Pod 的扩缩容就可以了，资源也不会有直接干扰，且外部/内部调用都是有统一的入口管理。

## 拆分的阵痛

### 业务接口聚合

在服务拆分的过程中，总是会有阵痛出现。例如在服务需要获取 “项目” 和 “房源” 信息时，到底是由谁来聚合这两个服务的信息。是不是应该由 BFF 来聚合：

![image](https://image.eddycjy.com/4fc07d0fb4a52ca1a0a4336fdd5e4db8.jpg)

或是应该新写一个胶水服务，用于聚合“项目” 和 “房源” 信息，保证其聚合性，减轻 BFF 的负担：

![image](https://image.eddycjy.com/7dc0d0f258e4e6cda6869455695ae050.jpg)

又或是在量级越来越多的情况下，是不是要怀疑一下，这两个服务拆分是不是有问题，“项目” 和 “房源” 在当前业务模型下是否应是一家：

![image](https://image.eddycjy.com/574dfe3c1294b2589cc0a640cd737cf4.jpg)

显然在鲤鱼的经历中，这三种类型他都见过，不同的人总会在不同的思想和业务模型下选择了不同的解决方案，还真的没有绝对准确的准则。

### 分久必合，合久必分

随着对服务化的进程推进，常见的会遇到两种情况：

- **刚接触服务化时**：服务一个没有，偶尔会有一个新的小业务，居然能拆出好好几个微型服务，并扬言要把剩余业务直接抄底重构了，都拆掉，怎么劝都劝不回头。

- **随着业务的不断发展**：快速迭代，服务越来越多，工期压缩，多个 RD 交叉背好几个业务服务，有点力不从心，发现拆的好像有点问题，从最新的情况来看，某某几个服务似乎应该合在一起。

- **业务阶段性稳定**：。。。这，以前这块好像有点问题，也太难拓展了，不应该这么拆，谁调了我，我的上下游是谁。

大多数的情况都是第二和第三者，但在实际操作中也不见得会合并服务，大多数 RD 会选择吞进心里，因为服务变迁所带来的工期延长和影响面无法直接预估（且存在历史代码，人员可能已经离职多年）。即使是服务拓扑也只能查看到一定时间内的服务调用，不会看到全部，因此上下游均无法 100% 确定。因此综合来看，弊大于利。

在解决方案上，更多的是在下次新服务规划时控制划分变量（因为已经有更成熟的经验了）。

实在不行了，才有可能会新起聚合服务将原本的多个服务聚合，又或是采取版本号等方式进行新老分流。甚至下定决心，蚂蚁搬家，起新服务一个个板块重构，一个个挪，持续灰度，“彻底” 解决历史包袱，完成转化。

## 拆分准则

张三又发话了，你说的我都懂，内部微服务都发展好几年了，作为已经有丰富研发经验的人，能不能释出一套微服务拆分的准则呢，否则每一个人都要经历一遍，怎么办，有没有什么基本准则可以遵守呢，你看现在 DDD 那么火，能不能 DDD 一下，让核心一致呢？

机智的鲤鱼掐指一算，张三肯定想的是让所有业务组的拆分，都能依据拆分的核心准则走，实现你中有我，我中有你，看哪哪都有影子，核心不跑偏就行，建立一套完美的方法核心论：

![image](https://image.eddycjy.com/ffd2a0d1e81011ea1a37b61e0f3b0513.jpg)

这种建议右拐 Google “微服务如何拆分”，网上有超级多的指导资料，建议先培养在团队内的共识。毕竟在每次拆服务时让每一个人都对照着那一长串的 “微服务拆分准则” 是一件很不科学的事情，更多的工程师会依据自身的经验进行当前其认为的最合理拆解。

而准则，你认为的核心 A，在他人眼里并不一定是正确，他可能认为是 B，因此在事业部，业务团队中达成共识并把拆分思想融合进每位 RD 思想中，长期的共同分析现在的拆分情况，且让大家基本认同才是最重要的。

同时让全公司都依据一个准则来做，在服务拆分这种无法利用工具流程强控制的情况，本身就是一个伪命题，更多的会是人与人之间的妥协，基本上会变成一个少有人看的 “指导” 文档。

## 总结

在微服务中，服务的拆分总是能让人如此细细品味，本文并不是具体的讲某几个知识点，更多的是阐述在服务化发展的历程中的 “冲突点” 又或是 “矛盾点”，不同的人总有不一样的理解，希望能够给大家带来一些思考。

且在阅读微服务相关指南时，更建议看企业实践后拆分的经验分享，否则单纯看 “指南” 没有过多的意义，要看具体的公司/团队情况和业务模型。

## 推荐阅读

Monorepo：

- [Why Google Stores Billions of Lines of Code in a Single Repository](https://cacm.acm.org/magazines/2016/7/204032-why-google-stores-billions-of-lines-of-code-in-a-single-repository/fulltext)

- [Monorepos: Please don’t!](https://medium.com/@mattklein123/monorepos-please-dont-e9a279be011b)

- [Why might a project/company use a monorepo?](https://dev.to/david_ojeda/comment/77k5)

Microservices：

- [Nginx Refactoring a Monolith into Microservices](https://www.nginx.com/blog/introduction-to-microservices/)

================================================
FILE: content/posts/microservice/flowcontrol-circuitbreaker.md
================================================
---
title: "限流熔断是什么，怎么做，不做行不行？"
date: 2020-10-05T13:24:16+08:00
toc: true
images:
tags: 
  - 微服务
  - 服务治理
---

“在分布式应用中，最常见的问题是什么呢？”

“一个分布式应用部署上去后，还要关注什么？”

![image](https://image.eddycjy.com/8c42e87dd4f7f1c59431c6185f608699.png)

“这服务的远程调用依赖似乎有点多...”

## 前言

在 [《微服务的战争：级联故障和雪崩》](https://eddycjy.com/posts/microservice/linkage/)中有提到，在一个分布式应用中，最常见，最有危险性之一的点就是级联故障所造成的雪崩，而其对应的解决方案为**根据特定的规则/规律进行流量控制和熔断降级**，避免请求发生堆积，保护自身应用，也防止服务提供方进一步过载。

![image](https://image.eddycjy.com/79a7f8870edffd331432272cf5db2c46.jpg)

简单来讲就是，要控制访问量的流量，要防各类调用的强/弱依赖，才能保护好应用程序的底线。

## 诉求，期望

1. 诉求：作为一个业务，肯定是希望自家的应用程序，能够全年无休，最低限度也要有个 4 个 9，一出突发性大流量，在资源贫乏的窗口期，就马上能够自动恢复。

2. 期望：万丈高楼平地起，我们需要对应用程序进行流量控制、熔断降级。确保在特定的规则下，系统能够进行容错，只处理自己力所能及的请求。若有更一步诉求，再自动扩缩容，提高系统资源上限。

## 解决方案

要如何解决这个问题呢，可以关注到问题的核心点是 “系统没有任何的保护的情况下”，因此核心就是让系统，让你的应用程序有流量控制的保护。一般含以下几个方面：

- 来自端控制：在业务/流量网关处内置流量控制、熔断降级的外部插件，起到端控制的效果。

- 来自集群/节点控制：在统一框架中内建流量控制、熔断降级的处理逻辑，起到集群/节点控制的效果。

- 来自 Mesh 控制：通过 ServiceMesh 来实现流量控制、熔断降级。侵入性小，能带来多种控制模式，但有利有弊。

以上的多种方式均可与内部的治理平台打通，且流量控制、熔断降级是不止面试应用程序的，就看资源埋点上如何设计、注入。常见有如下几种角度：

- 资源的调用关系：例如远程调用，像是面向 HTTP、SQL、Redis、RPC 等调用均，另外针对文件句柄控制也可以。

- 运行指标：例如 QPS、线程池、系统负载等。

## 流量控制

在资源不变的情况下，系统所能提供的处理能力是有限的。而系统所面对的请求所到来的时间和量级往往是随机且不可控的。因此就会存在可能出现突发性流量，而在系统没有任何的保护的情况下，系统就会在数分钟内无法提供正常服务，常见过程为先是出现调用延迟，接着持续出现饱和度上升，最终假死。

![image](https://image.eddycjy.com/6a58406bb7c90355c82c5cb50f417f9a.jpg)

流量控制一般常见的有两种方式，分别是：基于 QPS、基于并发隔离。

### 基于 QPS

最常用的流量控制场景，就是基于 QPS 来做流控，在一定的时间窗口内按照特定的规则达到所设定的阈值则进行调控：

![image](https://image.eddycjy.com/58f0d6fe0043963f6e40c1d73c8e019e.jpg)

#### 案例

在本文中借助 [sentinel-golang](https://github.com/alibaba/sentinel-golang) 来实现案例所需的诉求，代码如下：

```
import (
	...
	sentinel "github.com/alibaba/sentinel-golang/api"
	"github.com/alibaba/sentinel-golang/core/base"
	"github.com/alibaba/sentinel-golang/core/flow"
	"github.com/alibaba/sentinel-golang/util"
)

func main() {
	_ = sentinel.InitDefault()
	_, _ = flow.LoadRules([]*flow.Rule{
		{
			Resource:               "控制吃煎鱼的速度",
			Threshold:              60,
			ControlBehavior:        flow.Reject,
		},
	})

	...
	e, b := sentinel.Entry("控制吃煎鱼的速度", sentinel.WithTrafficType(base.Inbound))
	if b != nil {
	    // Blocked
	} else {
	    // Passed
	    e.Exit()
	}
}
```

总的来讲，上述规则结果就是 1s 内允许通过 60 个请求，超出的请求的处理策略为直接拒绝（Reject）。

首先我们初始化了 Sentinel 并定义资源（Resource）为 “控制吃煎鱼的速度”。其 Threshold 配置为 3，也就是 QPS 的阈值为 3，统计窗口未设置默认值为 1s，ControlBehavior 控制的行为为直接拒绝。

而在满足阈值条件后，常见的处理策略还有匀速排队（Throttling），匀速排队方式会严格控制请求通过的间隔时间，也就是让请求以均匀的速度通过。

### 基于并发隔离

基于资源访问的并发协程数来控制对资源的访问数量，主要是控制对资源访问的最大协程数，避免因为资源的异常导致协程耗尽。

![image](https://image.eddycjy.com/f255b874409c8a894b7254558b0828ca.jpg)

这类情况，Go 语言在设计上常常可以使用协程池来进行控制，但设计总是赶不上计划的，且不同场景情况可能不同，因此作为一个日常功能也是非常有存在的必要性。

## 熔断降级

在分布式应用中，随着不断地业务拆分，远程调用逐渐变得越来越多。且在微服务盛兴的情况下，一个小业务拆出七八个服务的也常有。

此时就会出现一个经典的问题，那就是客户端的一个普通调用，很有可能就要经过好几个服务，而一个服务又有可能远程调用外部 HTTP、SQL、Redis、RPC 等，调用链会特别的长。

若其中一个调用流程出现了问题，且没有进行调控，就会出现级联故障，最终导致系统雪崩：

![image](https://image.eddycjy.com/2e7b0d94c32f3bd8f3f7168046671d2b.jpg)


服务 D 所依赖的外部接口出现了故障，而他并没有做任何的控制，因此扩散到了所有调用到他的服务，自然也就包含服务 B，因此最终出现系统雪崩。

这种最经典的是出现在默认 Go http client 调用没有设置 Timeout，从而只要出现一次故障，就足矣让记住这类 “坑”，毕竟崩的 ”慢“，错误日志还多。（via: 《微服务的战争：级联故障和雪崩》）

### 目的和措施

为了解决上述问题所带来的灾难，在分布式应用中常需要对服务依赖进行熔断降级。在存在问题时，暂时切断内部调用，避免局部不稳定因素导致整个分布式系统的雪崩。

而熔断降级作为保护服务自身的手段，通常是在客户端进行规则配置和熔断识别：

![image](https://image.eddycjy.com/0fc0b2f9367d384d4ef0a6398054a8c6.jpg)

常见的有三种熔断降级措施：慢调用比例策略、错误比例策略、错误计数策略。

### 慢调用比例

在所设定的时间窗口内，慢调用的比例大于所设置的阈值，则对接下来访问的请求进行自动熔断。

### 错误比例

在所设定的时间窗口内，调用的访问错误比例大于所设置的阈值，则对接下来访问的请求进行自动熔断。

### 错误计数

在所设定的时间窗口内，调用的访问错误次数大于所设置的阈值，则对接下来访问的请求进行自动熔断。

## 实践案例

知道流量控制、熔断降级的基本概念和功能后，在现实环境中应该如何结合项目进行使用呢。最常见的场景是可针对业务服务的 HTTP 路由进行流量控制，以 HTTP 路由作为资源埋点，这样子就可以实现接口级的调控了。

![image](https://image.eddycjy.com/00c7676ca398bf4c5cc8725e69ce77b0.jpg)

还可以增强其功能特性，针对参数也进行多重匹配。常会有这种限流诉求：针对 `HTTP GET /eddycjy/info` 且 language 为 go 的情况下进行限流。另外还可以针对 HTTP 调用封装统一方法，进行默认的熔断注入，实现多重保障。

而结合系统负载、服务 QPS 等，可以对限流熔断的规则数据源进行实时调控，再结合 Watch 机制，就能够比较平滑的实现自适应限流熔断的接入。

## 总结

在分布式应用中，限流熔断是非常重要的一环，越早开始做越有益处。但需要注意的是，不同公司的业务模型多多少少有些不一样，所针对的匹配维度多少有些不同，因此需要提前进行业务调研。

且在做业务的限流熔断时，注意把度量指标的打点做上，这样子后续就能够结合 Prometheus+Grafana+Alertmanager 做一系列的趋势图，熔断告警，自动扩缩容等相关工作了，会是一个很好的助力。

================================================
FILE: content/posts/microservice/leaky-token-buckets.md
================================================
---
title: "带你快速了解：限流中的漏桶和令牌桶算法"
date: 2020-10-06T12:44:10+08:00
toc: true
images:
tags: 
  - 微服务
  - 服务治理
---

在前文 《限流熔断是什么，怎么做，不做行不行？》中针对 “限流” 动作，有提到流量控制其内部对应着两种常用的限流算法，分别是漏桶算法和令牌桶算法。因此会有的读者会好奇，这都是些啥？

为了更进一步的了解 WHY，本文来快速探索一下，看看限流下的一些 “算法” 们到底有何作用，是为何成为流量控制的基石的？

![image](https://image.eddycjy.com/815f7524b5367149cc9c6725ee28cd12.jpg)

## 前言

理论上每一个对外/内提供功能的资源点，都需要进行一定的流量控制，否则在业务的持续迭代中，是有可能出现突发性流量的场景（就像年初所带来的一些行业突发转变，导致业务流量突然暴增）：

![image](https://image.eddycjy.com/c29272e53f9e125dbbfba133b3eea7c4.jpg)

若没有进行限流，就会出现一些奇奇怪怪的问题点，实则就是系统无法承受这波流量，逐渐崩溃，走向系统假死。

## 现实场景

最常见的现实场景就是日常随处可见的排插、插座，其内置的保险丝，也被称为电流保险丝，其主要是起过载保护作用，保险丝会在电流异常升高到一定的高度和热度的时候，自身熔断切断电流，从而起到保护电路安全运行的作用。

因此真实世界中有许多与软件工程中的限流熔断的场景有异曲同工之处，也是为了控制量，超量就切断。你也可以想想现实生活中是否有遇到其他类似的例子呢？

![image](https://image.eddycjy.com/23af65486fc991e1bd976c37626ccf18.jpg)

## 漏桶算法（Leaky Bucket）

漏桶算法（Leaky Bucket）是网络中流量整形（Traffic Shaping）或速率限制（Rate Limiting）时常用的一种算法，它的主要目的是控制数据注入到网络的速率，平滑网络上的突发流量。

漏桶算法通过其算法调控了流量访问，使得突发流量可以被整形，去毛刺，变成一个相对缓和，以便为网络提供一个稳定的流量。

漏桶算法的存储桶主要由三个参数定义，分别是：桶的容量、水从桶中流出的速率、桶的初始充满度。

其核心理念就如字面意思：一个会漏水的桶。

![图片来自 geeksforgeeks](https://image.eddycjy.com/386bdd6a907a2130f5bfa74696817221.jpg)

### Bursty Flow

在上图中，水龙头代表着突发流量（Bursty Flow）。当网络中存在突发流量，且无任何调控时，就会出现像 Bursty Data 处类似的场景。主机以 12 Mbps 的速率发送数据，时间持续 2s，总计 24 Mbits 数据。随后主机暂停发送 5s，然后再以 2 Mbps 的速率发送数据 3s，最终总共发送了 6 Mbits 的数据。

因此主机在 10s 内总共发送了 30 Mbits 的数据。但这里存在一个问题，就是数据的发送并不是平滑的，存在一个较大的波峰。若所有流量都是如此的传输方式，将会 “旱的旱死涝的涝死”，对系统并不是特别的友好。

### Fixed Flow

为了解决 Bursty Flow 场景的问题。漏桶（Leaky Bucket）出现了，漏桶具有固定的流出速率、固定的容量大小。

在上图中，漏桶在相同的 10s 内以 3 Mbps 的速率持续发送数据来平滑流量。若水（流量）来的过猛，但水流（漏水）不够快时，其最终结果就是导致水直接溢出，呈现出来就是拒绝请求/排队等待的表现。另外当 Buckets 空时，是会出现一次性倒入达到 Bucket 容量限制的水的可能性，此时也可能会出现波峰。

简单来讲就是，一个漏桶，水流进来，但漏桶只有固定的流速来流出水，若容量满即拒绝，否则将持续保持流量流出。

## 令牌桶算法

令牌桶算法也是网络中流量整形或速率限制时常用的一种算法，它的主要目的是控制发送到网络上的数据的数目，并允许突发数据的发送。

令牌桶算法会以一个恒定的速率向桶里放入令牌，如果有新的请求进来希望进行处理，则必须要先从桶内拿到一个可用的令牌，才能继续被处理。若桶内无令牌可取时，则拒绝请求/排队等待。

![图片来自 gateoverflow](https://image.eddycjy.com/07c0861b3a2e900ea4ca6fc8f7aeaa1a.jpg)

1. 每 1/r 秒新增一个 token 到 buckets 中。

2. buckets 中最多可容纳 b 个令牌。如果桶已满，将丢弃这个新增的 token（也就是不需要新的 token）。

3. 当主机传输 n bytes packets 時，buckets 中如果有 n 个令牌，则取到所需令牌，成功传输 n bytes。

4. 当可用的 token 小于 n bytes 时，不会从 buckets 中取到任何 token，本次请求将被拒绝/排队等待。

## 漏桶 vs 令牌桶

漏桶算法和令牌桶算法本质上都是为了做流量整形（Traffic Shaping）或速率限制（Rate Limiting），避免系统因为大流量而被打崩，但两者核心差异在于限流的方向是相反的。

令牌桶限制的是流量的平均流入速率，并且允许一定程度的突然性流量，最大速率为桶的容量和生成 token 的速率。而漏桶限制的是流量的流出速率，是相对固定的。

因此也会相对的带来一个问题，在某些场景中，漏桶算法并不能有效的使用网络资源，因为漏桶的漏出速率是相对固定的，所以在网络情况比较好，没有拥塞的状态下，漏桶依然是限制住的，并没有办法放开量。而令牌桶算法则不同，其能够是限制平均速率的同时支持一定程度的突发流量。

## 总结

在软件系统中，限流常常所代表的就是流量整形、速率限制，是一个非常常见的调控手段。一般我们会将其在初期集成到统一框架、网关、Mesh 中去。因此建议接触业务的同学，都要对这一块进行考量，便于后续的快速使用/接入，毕竟业务的流量爆发总是来的比较突然，甚至可能是恶意攻击。

而本文所提到的漏桶，令牌桶都是非常常见的手段，虽然两者独立出来分析了。但从软件开发的角度来讲，你认为两者是否可以融合，结合其优势呢？

================================================
FILE: content/posts/microservice/linkage.md
================================================
---
title: "微服务的战争：级联故障和雪崩"
date: 2020-08-25T21:08:39+08:00
toc: true
images:
tags: 
  - 微服务
---

> “微服务的战争” 是一个关于微服务设计思考的系列题材，主要是针对在微服务化后所出现的一些矛盾/冲突点，不涉及具体某一个知识点深入。如果你有任何问题或建议，欢迎随时交流。

在 [微服务的战争：统一且标准化](https://eddycjy.com/posts/microservice/standardization/) 中，经过好几周与不同业务组不同事业部的跨部门讨论后，终于把初始的标准化方案给定下来了，大家欢快的使用起了内部的统一框架，疯狂的创建起了新服务，没隔多久服务调用链就变成了下图：

![image](https://image.eddycjy.com/97128d96a1a4b8ba1f765bf30134f529.jpg)

服务间存在多次内部调用，服务 A =》服务 B =》服务 C =》服务D，而 服务 E =》 服务 B，服务 F =》服务 E，也就是存在着多个流量入口，且依赖相同的服务。

## 背景

服务与服务中，总存在业务服务，公共服务，基础服务等类型。但在某一个夜晚，突然发现 BFF 调用后端服务开始逐渐不正常，客户给你截图反馈问题，你发现有点问题：

![image](https://image.eddycjy.com/844d0d5a730a4c692d7d96912e1d710c.jpg)

单从表现来看，你发现是 BFF 调用服务 A 极度缓慢，也不知道怎么了...正当以为是服务 A 出问题，想着万能重启一下时。你在日志平台和链路追踪系统一看，发现了大量的错误日志和缓慢，让你略微震惊，一时间不知道从何下手。

这可怎么办？

## 级联故障和雪崩

实际上这是一次很经典的级联故障，最终导致系统雪崩的情景再现。单从上述拓扑来看，问题点之一在于服务 B：

![image](https://image.eddycjy.com/51b18e7c80833fbe1dc13b3a3290940b.jpg)

服务 B 本身作为服务 A 和服务 F 的两个流量入口必经之处，想必至少是一个公共服务，但他也依赖了其他多个服务。因此若服务 C 和服务 D 其中一个有问题，在没有熔断措施的情况下，就出现级联故障，系统逐渐崩盘，最后雪崩：

![image](https://image.eddycjy.com/2e7b0d94c32f3bd8f3f7168046671d2b.jpg)

服务 D 所依赖的外部接口出现了故障，而他并没有做任何的控制，因此扩散到了所有调用到他的服务，自然也就包含服务 B，因此最终出现系统雪崩。

这种最经典的是出现在默认 Go http client 调用没有设置 Timeout，从而只要出现一次故障，就足矣让记住这类 “坑”，毕竟崩的 ”慢“，错误日志还多。

## 解决方法

常见的方式是**根据特定的规则/规律进行熔断和降级**，避免请求发生堆积：

- 超时时间控制。

- 慢调用比例。

- 错误比例。

- 自适应（例如：负载情况等）。

当然，这也只是壮士断腕，后续措施还包含监控告警，通知对应的开发人员来处理。且需提前对被降级的模块进行业务逻辑进行处理等等，这样才能够比较柔和且快速地度过这一次危机。

## 总结

在分布式应用中，级联故障和雪崩是非常常见的，一些开发同学在模块设计时可能并没有意识到这块的问题，在微服务化后会一个不留神就碰到，因为其调用链变得特别的长且多。因此建议配套设施和限流熔断措施都应该及时跟上，否则面对一大堆的错误日志还是很无奈的。

同时，监控告警的建设也要做，因为在危机出现时，有一个 HTTP 调用的 P95/P99 告警出现，那就比较舒心了，直接 root cause。

================================================
FILE: content/posts/microservice/monitor-alarm.md
================================================
---
title: "想要4个9？本文告诉你监控告警如何做"
date: 2020-09-13T18:42:17+08:00
toc: true
images:
tags: 
  - 微服务
  - 服务治理
---

“你说说，没有仪表盘的车，你敢开吗？”

“没有仪表盘的车开在路上，你怎么知道现在是什么情况？”

![image](https://image.eddycjy.com/6e2774d84ddcdb2d73918e06575a07b7.jpeg)

“客户说你这车又崩了，咋知道什么时候好的？​啥时候出的问题？”

## 前言

将思考转换到现实的软件系统中，可想而知没有监控系统的情况下，也就是没有 ”仪表盘“ 的情况下实在是太可怕了。

你的故障永远都是你的客户告诉你的，而...在什么时候发生的，你也无法确定，只能通过客户的反馈倒推时间节点，最后从错误日志中得到相对完整的日志信息。

## 问题

更要命的是你无法掌握主动权，错误日志有可能会有人漏记录，平均修复时间（MTTR）更不用想了，需要从 0.1 开始定位，先看 APP 是哪个模块报错，再猜测是哪个服务导致，再打开链路追踪系统，或是日志平台等。

稍微复杂些的，排查来来往往基本都是半小时、一小时以上，那 4 个 9 肯定是达不到的了，以此几次 P0 几小时怕不是业务绩效也凉凉，因为故障修复的速度实在是太慢了。

那归根到底，想破局怎么办，核心第一步就是要把监控告警的整个生态圈给建设好。

## 监控定义

常说监控监控，监控的定义就是监测和控制，检测某些事物的变化，以便于进行控制。在常见的软件系统中，大多分为三大观察类别：

![image](https://image.eddycjy.com/b567a71921b7e54d703d9e47f491d6c0.jpg)

- 业务逻辑：项目所对应的服务其承担的业务逻辑，通常需要对其进行度量。例如：每秒的下单数等。

- 应用程序：应用程序。例如：统一的基础框架。

- 硬件资源：服务器资源情况等。例如：Kubernetes 中的 Cadvisor 组件便会提供大量的资源指标。

从软件系统来讲，监控的定义就是收集、处理、汇总，显示关于某个系统的实时量化数据，例如：请求的数量和类型，错误的数量和类型，以及各类调用/处理的耗时，应用服务的存活时间等。

## 监控目标

知道了监控的定义，了解了监控的作用和具体的实施指标后。我们需要明确的知道，做监控的目标是什么：

![image](https://image.eddycjy.com/bab6275c4b7c73deec2d9f9919f967c7.jpg)

从现实层面出发，做监控的初衷，就是希望能够及时的发现线上环境的各种各样奇奇怪怪的问题，为业务的正常运转保驾护航。因此整体分为上图四项：

- 预测故障：故障还没出现，但存在异常。监控系统根据流量模型、数据分析、度量趋势来推算应用程序的异常趋势，推算可能出现故障的问题点。

- 发现故障：故障已经出现，客户还没反馈到一线人员。监控系统根据真实的度量趋势来计算既有的告警规则，发现已经出现故障的问题点。

- 定位故障：故障已经出现，需要监控系统协助快速定位问题，也就是根因定位（root cause）。此时是需要协调公司内生态圈的多个组件的，例如：链路追踪系统、日志平台、监控系统、治理平台（限流熔断等），根据监控系统所告警出来的问题作为起始锚点，对其进行有特定方向的分析，再形成 ”线索“ 报告，就可以大力的协助开发人员快速的定位问题，发现故障点。

- 故障恢复：故障已经出现，但自动恢复了，又或是通过自动化自愈了。这种情况大多出现在告警规则的阈值配置的不够妥当，又或是第三方依赖恰好恢复了的场景。

而更值得探讨的的是监控告警的后半段闭环，故障自愈，通过上述三点 “预测故障、发现故障、定位故障”，已经定位到故障了，就可以配合内部组件，实现自动化的 ”自愈“，减少人工介入，提高 MTTR。

![image](https://image.eddycjy.com/437e9d859ee86916f5d2d0bc409ab9f5.jpg)

因此做监控系统的目标很明确，就是发现问题，解决问题，最好自愈，达到愉快休假，业务安心的目的。

## 4 个黄金指标

有定义，有目标，那指导呢。实际上 “业务逻辑、应用程序、硬件资源” 已经成为了一个监控系统所要监控构建的首要目标，绝大部分的监控场景都可以归类进来。且针对这三大项，《Google SRE 运维解密》 也总结出了 4 个黄金指标，在业界广为流传和借鉴：

- 延迟：服务处理某个请求所需要的时间。
    - 区分成功和失败请求很重要，例如：某个由于数据库连接丢失或者其他后端问题造成的 HTTP 500 错误可能延迟很低。因此在计算整体延迟时，如果将 500 回复的延迟也计算在内，可能会产生误导性的结果。
    - “慢” 错误要比 “快” 错误更糟糕。

- 流量：使用系统中的某个高层次的指标针对系统负载需求所进行的度量。
    - 对 Web 服务器来讲，该指标通常是每秒 HTTP 请求数量，同时可能按请求类型分类（静态请求与动态请求）。
    - 针对音频流媒体系统来说，指标可能是网络 I/O 速率，或者并发会话数量。
    - 针对键值对存储系统来说，指标可能是每秒交易数量，或每秒的读者操作数量。

- 错误：请求失败的速率。
    - 显式失败（例如：HTTP 500）。
    - 隐式失败（例如：HTTP 200 回复中包含了错误内容）。
    - 策略原因导致的失败（例如：如果要求回复在 1s 内发出，任何超过 1s 的请求就都是失败请求）。

- 饱和度：服务容量有多 “满”，通常是系统中目前最为受限的某种资源的某个具体指标的度量，例如：在内存受限的系统中，即为内存；在 I/O 受限的系统中，即为 I/O。
    - 很多系统在达到 100% 利用率之前性能会严重下降，因此可以考虑增加一个利用率目标。
    - 延迟增加是饱和度的前导现象，99% 的请求延迟（在某一个小的时间范围内，例如一分钟）可以作为一个饱和度早期预警的指标。
    - 饱和度需要进行预测，例如 “看起来数据库会在 4 小时内填满硬盘”。

如果已经成功度量了这四个黄金指标，且在某个指标出现故障时能够发出告警（或者快要发生故障），那么在服务的监控层面来讲，基本也就满足了初步的监控诉求。

也就是可以做到知道了是什么出问题，问题出在哪里，单这一步就已经提高了不少定位问题的时间效率，是一个从 0 到 1 的起步阶段。

## 实践案例

知道是什么（定义），为什么要做（目标），做的时候需要什么（4 个黄金指标）后，还缺乏的是一个承载这些基础应用、业务思考的平台，让架构+运维+业务共同在上面施展拳脚。

公司内部至少需要有一个监控告警管理平台。

### 平台搭建

在目前云原生火热的情况下，Kubernetes 生态中大多惯用 Prometheus，因此 Prometheus+Grafana+AlertManger 成为了一大首选，业内占比也越来越高，其基本架构如下：

![image](https://image.eddycjy.com/d6c347759dbe7eb9c14c544b6bbab468.jpg)

- Prometheus Server：用于收集指标和存储时间序列数据，并提供一系列的查询和设置接口。
- Grafana：用于展示各类趋势图，通过 PromQL 从 Prometheus 服务端查询并构建图表。
- Alertmanager：用于处理告警事件，从 Prometheus 服务端接收到 alerts 后，会进行去重，分组，然后路由到对应的Receiver，发出报警。

这块具体的基本知识学习和搭建可详见我写的 [Prometheus 系列](https://eddycjy.com/prometheus-categories/)，本文不再赘述。

### 监控指标

在平台搭建完毕后，常要做的第一步，那就是规划你整个系统的度量指标，结合 Google SRE 的 4 个黄金指标，可以初步划分出如下几种常用类型：

- 系统层面：Kubernetes Node、Container 等指标，这块大多 Cadvisor 已采集上报，也可以安装 kube-state-metrics 加强，这样子就能够对 Kubernetes 和应用程序的运行情况有一个较好的观察和告警。

- 系统层面：针对全链路上的所有基础组件（例如：MySQL、Redis 等）安装 exporter，进行采集，对相关基础组件进行监控和告警。

- 业务服务：RPC 方法等的 QPS 记录。可以保证对业务服务的流量情况把控，且后续可以做预测/预警的一系列动作，面对突发性流量的自动化扩缩容有一定的参考意义。

- 业务服务：RPC 方法等的错误情况。能够发现应用程序、业务的常见异常情况，但需要在状态/错误码规划合理的情况下，能够起到较大的作用，有一定困难，要在一开始就做对，否则后面很难扭转。

- 应用程序：各类远程调用（例如：RPC、SQL、HTTP、Redis）的调用开销记录。最万金油的度量指标之一，能够在很多方面提供精确的定位和分析，Web 应用程序标配。常见于使用 P99/95/90。

- 语言级别：内部分析记录，例如：Goroutines 数量、Panic 情况等，常常能发现一些意想不到的泄露情况和空指针调用。没有这类监控的话，很有可能一直都不会被发现。

### 指标落地

第一步完成了整个系统的度量指标规划后，第二步就是需要确确实实的把指标落地了。

无论是统一基础框架的打点，系统组件的 exporter，大多涉及了公司级的跨多部门协作，这时候需要更多的耐心和长期主义和不断地对方向纠错，才能尝到体系建设后的果实。

### 告警体系

在完成监控指标和体系的建设后，告警如何做，成为了一大难题，再好的监控体系，闭环做不好，就无法发挥出很大的作用。因此我们给告警定义一些准则：

1. 告警不要太多，否则会导致“狼来了”。

2. 告警出现时，应当要具体操作某些事情，是亟待解决的。

3. 告警出现时，应当要进行某些智力分析，不应该是机械行为。

4. 不需要人工响应/处理的告警规则，应当直接删除。

5. 告警出现时，你下意识要再观察观察的告警，要直接进行调整。

6. 告警应当足够的简单，直观，不需要猜。

简单来讲就是告警要少，事件需要解决，处理要人工介入。否则右拐自动化自愈恢复可能更香。

#### 告警给谁？

另外一个难题就是：
谁诱发处理的告警，要通知给谁？

这是一个很需要斟酌的问题，在告警的规范上，尽可能遵循最小原则，再逐级上报。也就是先告警给 on-call 人，若超出 X 分钟，再逐级上报到全业务组，再及其负责人，一级级跟踪，实现渐进式告警。

![image](https://image.eddycjy.com/6745789c92ca3f7bc0fd86909046ce45.jpg)

逐级上报，响应即跟踪，明确问题点的责任人。而逐级上报的数据来源，可通过员工管理系统来获取，在员工管理系统中有完整的上下级关系（类似 OA 审批上看到的流程节点），但如果该系统没有开放 API 之类的，那可能你只能通过其他方式来获取了。

例如像是通过企业微信获取部门关系和人员列表，再手动设置上下级关联关系，也可以达到目的，且在现实世界中，有可能存在定制化的诉求。

### 规范建立

即使所以监控体系、指标落地、告警体系都建立起来了，也不能掉以轻心。实际上在成为事实标准后，你仍然需要尽快为告警后奔跑，将整个闭环搭建起来，也就是故障管理。

与公司内部的流程管理的同学或 QA，一起设立研发底线的规范，进行细致的告警分级识别，告警后的汇总运营分析，形成一个真正意义上的故障管理规范。

否则最后可能会疲于奔命，人的时间精力总是有限的，而面对整个公司的监控告警的搭建，体系上与业务组的共建，督促告警响应，极有可能最后会疲于奔命，即使真的有一定用处，在杂乱无人收敛的告警中最后流于形式。

## 总结

监控告警的体系生态做来有意义吗？

这是必然的，成熟且规范的监控告警的体系生态是具有极大意义，可以提前发现问题，定位问题，解决问题。甚至这个问题的说不定还不需要你自己处理，做多组件的闭环后，直接实施自动化的服务自愈就可以了，安心又快快乐乐的过国庆节，是很香的。

而故障管理的闭环实施后，就可以分析业务服务的告警情况，结合 CI/CD 系统等基础平台，每季度自动化分析实施运营报表，帮助业务发现更多的问题，提供其特有的价值。

但，想真正做到上述所说的成熟且规范，业务共建，有难度，需要多方面认同和公司规范支撑才能最佳实现。因此共同认可，求同存异，多做用户反馈分析也非常重要。

================================================
FILE: content/posts/microservice/standardization.md
================================================
---
title: "微服务的战争：统一且标准化"
date: 2020-08-22T21:56:14+08:00
toc: true
images:
tags: 
  - 微服务
---

> “微服务的战争” 是一个关于微服务设计思考的系列题材，主要是针对在微服务化后所出现的一些矛盾/冲突点，不涉及具体某一个知识点深入。如果你有任何问题或建议，欢迎随时交流。

![image](https://image.eddycjy.com/b70c37b40768191e5a6812096703a63f.jpg)

## 开天辟地

在远古开天辟地时，大单体转换成微服务化后，服务的数量越来越多。每起一个新的服务，就得把项目的目录结构，基础代码重新整理一遍，并且很有可能都是从最初的 template 上 ctrl+c，ctrl+v 复制出来的产物，如下：

![image](https://image.eddycjy.com/7b4642c2bb7af1e5656be047bc269fb6.jpg)

但是基于 template 的模式，很快就会遇到各种各样的新问题：

![image](https://image.eddycjy.com/3c91559190480a348aeacd609199c2bb.jpg)

随着跨事业部/业务组的使用增多，你根本不知道框架的 template 是什么时间节点被复制粘贴出去的，也不知道所对应的 commit-id 是什么，更不知道先前的 BUG 修复了没，也不知道有没有其他开发人员私下改过被复制走的 template。

简单来讲，就是不具备可维护性，相对独立，BUG 可能一样，但却没有版本可规管。这时候，就可以选择做一个内部基础框架和对应的内部工具（已经有用户市场了），形成一个脚手架闭环：

![image](https://image.eddycjy.com/3787e41616779a91a3a052467b3acdee.jpg)

通过基础工具+基础接口的方式，就可以解决项目A、B、C...的基础框架版本管理和公共维护的问题，且在遇到框架 BUG 时，只需要直接 upgrade 就好了。而在框架维护者层面，还能通过注册机制知道目前基础框架的使用情况（例如：版本分布），便于后续的迭代和规划。

同时若内部微服务依赖复杂，可以将脚手架直接 “升级”，再做多一层基础平台，通过 CI/CD 平台等关联创建应用，选择应用类型等基本信息，然后关联创建对应的应用模板、构建工具、网关、数据库、接口平台、初始化自动化用例等：

![image](https://image.eddycjy.com/0997fb71080b8f35fe0ccd68acaebc94.jpg)

至此，就可以通过结合基础平台（例如：CI/CD）实现流程上的标准化控制，成为一个提效好帮手。

## 大众创新

但，一切都有 “开天辟地” 那么顺利吗。实际上并不，在很多的公司中，大多数是在不同的时间阶段在不同的团队同时进行了多个开天辟地。

更具现化来讲，就是在一家公司内，不同的团队里做出了多种基础工具和基础框架。更要命的是，他们几家的规范可能还不大一样。例如：框架在 gRPC 错误码的规范处理上的差异：

- 业务错误码放在 grpc.status.details 中。

- 业务错误码放在 grpc-status 中。

- 业务错误码放在 grpc-message 中。

又或是 HTTP 状态码的差异：

- HTTP Status Code 为金标准，不在主体定义业务错误码。

- HTTP Status Code 都为 200 OK（除宕机导致的 500，503 等），业务错误码由主体另外定义。

粗略一看，单单在应用错误码/状态码这一件事情上，就能够玩出花样。而这件事又会导致各种问题，例如在监控平台上，因为不同团队所定义的状态码规范不一样，就会导致连基本的监控可用性都会有问题。

像是有的小伙伴会把业务错误码放在 grpc-status 属性中，而在标准 gRPC 的规范中 grpc-status 是和 HTTP Status Code 一样有特定状态码映射的。这时候就会让监控告警系统十分难做，通用的告警规则到底是以哪份状态码为准？

![image](https://image.eddycjy.com/34c3c8c97f1f6164d94fb7ce7ada8262.jpg)

往往最终演进的路线与企业的组织结构有关，也就是[康威定律](https://zh.wikipedia.org/wiki/%E5%BA%B7%E5%A8%81%E5%AE%9A%E5%BE%8B)，一个系统的技术边界反映组织的结构。业界常见的是两种情况：

1. A 吞并 B，B 与 A 一致，从例子上来讲就是基本公用一套（维度为公司/事业部/业务组级别，与企业情况有关）。

2. A，B 均独立发展，从例子上来讲就是均独立搭建，各管各，偶尔互相触碰边界，又或是在公开分享暗中切磋。

显然，这其中利与弊就要各自判断了，多少厂内部有多少个框架，也有血汗厂基本一统江湖的，可能做基础架构适配的小伙伴会比较有感触，不同框架的 Header 规范不一样，这样子即使是 Mesh 也避免不了一顿 if else。

更甚的是，在类似服务发现/注册、限流熔断、基础拦截器，各类 SDK 同个厂的每个内部框架都重现实现一遍。美其名曰框架支持了这些，就允许让他上，但这样子怕是在未来又造成了新的一波技术债务。

同时框架维护者，是有可能离职跳槽到别家去的，这在前端届也层出不穷，带着修炼好的真经走了，留下一个没有人维护的组内框架，这时候只能硬着头皮找 B/C 角来接受，顶上来的人指不定思想还不一样。

这单从公司层面来讲，是一个巨大的伤害，长远来看着实是灾难。

## 总结

在本文中，主体分为了 “开天辟地” 和 “大众创新” 两块内容，理想是丰满的，而现实怕是很骨感。微服务是一把双刃剑，带来好处的同时往往也带来了反面，架构的复杂度很难预知，因此本质上需要一个基架团队不忘初心，持续发现，持续解决问题。

但不论如何，及早的把主力语言、基本技术栈均基本统一起来，做好产品闭环，会是一个很好的方向。

如果具体到要做的事情，需要有一个明事理的上级，清晰的意识到同个子公司内的技术体系最好是基本一致的，由基础架构组或相关领头人拉齐核心 Leader，定义基本规范，构建统一框架，融合 CI/CD 平台。

![image](https://image.eddycjy.com/3b2653c1e548206f5c3893c82765ce29.jpg)

当然，反之倒推也是可以的（野蛮生长），就是步骤更多了，更难了。




================================================
FILE: content/posts/microservice/tests.md
================================================
---
title: "微服务的灾难：端到端测试的痛苦"
date: 2020-09-10T19:54:59+08:00
toc: true
images:
tags: 
  - 微服务
---

大家好，我是煎鱼。

小咸鱼经过前文所提到的折磨人的 “微服务拆分、微服务环境” 问题后，终于顺顺利利的上到了测试环境进行测试。

这时候开发、测试同学又闹新的头疼了，测了一轮下来。发现好好的。结果发现一上生产就有一些地方有问题，发现没测到。

这到底是为什么呢？

## 背景

在以往，小咸鱼他们团队都是传统的大单体应用。也就是一体化应用，包含了前端、后端等模块，具备天然的协调性：
- 测试同学能够很方便的就直接测到前后端接口。
- 测试能够直接对系统本身进行集成测试。

但现在，做了微服务化（雏形）后，小咸鱼他们就翻车了，为什么呢？

因为考虑到微服务，微服务就是向往单拎一个服务出来，都可以独立修改，独立发布。于是小咸鱼提交了一个迭代的几个服务变更，想着实现一把 “敏捷” 发布。

结果一上线就炸了，一大堆的 BUG，光荣加班到晚上 12 点。

这实质上是缺乏端到端测试的一个问题，单服务，无法明确系统正在正常运行。

## 端到端测试

在测试的质量保障上，我们要站在用户视角去验证这个系统，保障整体的系统可用性，而不是单纯的前端 BFF，又或是后端 Server 的某些接口能够正常运行。

在定义上**端到端测试（End-to-end Test）是一种用于测试整个应用程序的流程是否符合预期的测试技术**。测试同学会模拟用户真实的使用场景，通过用户界面测试应用程序。

如下图：

![端到端测试](https://image.eddycjy.com/5ca5b971d8e25cf41c648401489d47b4.jpg)

与小咸鱼团队那种单纯只测接口的方式不同，端到端测试是面向业务的。

其目的是**验证应用程序系统整体上是否符合业务诉求**，主要通过 GUI 测试，也会有人称其为集成测试、系统测试，黑盒测试。不少公司会将这几种混在一起。

实则在细节定义上各有不同：

![图来自网络](https://files.mdnice.com/user/3610/820d7fbb-e3aa-4e99-8898-d69fa242887b.png)

本文不是测试方向文章，因此不深究。

## 问题症结

那么小咸鱼他们团队主要是缺乏端到端的这类集成测试的校验。直接在迭代中，把几个微服务一改，接口跑几下，以为就是合理通过的了。

真实情况：
- 一上到生产，发现压根不是这么回事。因为多个变更结合在一起，很有可能会导致系统原有的行为发生改变。
- 即使是你单个服务接口没违背，也不一定能保证其他在同个时段上的服务没问题。
- 在业内执行情况来看，业务迭代的非常快，接口自动化大多比较缺乏。又或是以请外包人员的方式来做，大多是面向存量补接口。

我们可以知道单纯验证接口，不走端到端类别的集成测试，是非常风骚的。设身处地的想想如下场景：

有没有见过一些开发，他在本地测好接口后，一和前端集成上到测试环境。测试人员，一点一个报错，正向流程压根跑不通。测试同学苦不堪言，开发同学一下身背数十 BUG，齐齐加班。

但开发同学大呼我在本地的接口测试的完全没问题。归根结底，小咸鱼团队的问题，还是因为缺乏端到端测试，缺乏齐全的接口自动化用例导致的。

## 解决思路

在每个迭代中，实际上每个团队都会专注于系统中所使用的所有服务中的某个服务。

系统中存在的大量微服务和子系统的功能和较窄的测试空间，有可能会导致没有发现系统或服务中存在的隐患。

这样测试，问题的出现，甚至是必然的。

在解决思路上常见于：

1. 新增预发布环境，做类似端到端测试的集成测试，确保系统集成后会是可用的。
2. 尝试更高覆盖率的接口自动化测试，大多数公司会针对新的，做增量或存量的自动化测试用例的补全。
3. 借助线上、线下数据在 CI/CD 时进行自动化测试，实现更全面真实的测试用例。

业内基本是数种思路齐头并进，最常见的是第一种方式。最有效，但开销也是最大的，并且会导致预发布环境的一定阻塞。

随后第二第三种大多都会紧接着跟进，具体程度会根据公司的软硬实力（例如：行政手段、基础设施等）不同而做的深度不同。

甚至前几天听小咸鱼说，面试时还听到不少公司延伸了外包岗位专门做一块的内容。

## 总结

虽说这个问题并不是 “微服务” 架构所独有的。但是显然微服务化后放大了测试的深坑问题。

很多公司的流程和措施都是为了保障一些东西，像小咸鱼团队这样，被网上布道师例举的优点遮蔽了双眼，后面又被迫把端到端测试加回来的不在少数。

**你们的团队又是如何高效解决这个问题的呢，欢迎在评论区留言和交流**！

================================================
FILE: content/posts/microservice/tracing.md
================================================
---
title: "微服务的战争：选型？分布式链路追踪"
date: 2020-09-10T19:53:59+08:00
toc: true
images:
tags: 
  - 微服务
---


> “微服务的战争” 是一个关于微服务设计思考的系列题材，主要是针对在微服务化后所出现的一些矛盾/冲突点，不涉及具体某一个知识点深入。如果你有任何问题或建议，欢迎随时交流。

## 背景

在经历 [微服务的战争：级联故障和雪崩](https://eddycjy.com/posts/microservice/linkage/) 的 P0 级别事件后，你小手一摊便葛优躺了。开始进行自我复盘，想起这次排查经历，由于现在什么基础设施都还没有，因此在接收到客户反馈后，你是通过错误日志进行问题检查的。

但在级联错误中，错误日志产生的实在是太多了，不同的服务不同的链路几乎都挤在一起，修复时间都主要用在了翻日志上，翻了好几页才找到了相对有效的错误信息。

如果下一次在出现类似的问题，可不得了，MTTR 太久了，4 个 9 很快就会用完。这时候你想到了业界里经常被提起的一个利器，那就是 “分布式链路追踪系统”。粗略来讲，能够看到各种应用的调用依赖：

![image](https://image.eddycjy.com/e233f218a90b7a00b94b7f533a98c0a2.png)

其中最著名的是 [Google Dapper](https://storage.googleapis.com/pub-tools-public-publication-data/pdf/36356.pdf) 论文所介绍的 Dapper。源于 Google 为了解决可能由不同团队，不同语言，不同模块，部署在不同服务器，不同数据中心的所带来的软件复杂性（很难去分析，无法做定位），构建了一个的分布式跟踪系统：

![image](https://image.eddycjy.com/64214cb247989300859b98b61a844c2e.png)

自此就开启了业界在分布式链路的启发/启蒙之路，很多现在出名的分布式链路追踪系统都是基于 Google Dapper 论文发展而来，基本原理和架构都大同小异。若对此有兴趣的可具体查看 [Google Dapper](https://storage.googleapis.com/pub-tools-public-publication-data/pdf/36356.pdf)，非常有意思。

![image](https://image.eddycjy.com/65bd2c9b931f057d7307dfaaa8d5c433.png)

（Google Dapper 中存在跟踪树和 Span 的概念）

## 选型？有哪些

想做链路追踪，那必然要挑选一款开源产品作为你的分布式链路追踪系统，不大可能再造一个全新的，先实现业务目的最重要。因此在网上一搜，发现如下大量产品：

- Twitter：Zipkin。
- Uber：Jaeger。
- Elastic Stack：Elastic APM。
- Apache：SkyWalking（国内开源爱好者吴晟开源）。
- Naver：Pinpoint（韩国公司开发）。
- 阿里：鹰眼。
- 大众点评：Cat。
- 京东：Hydra。

随手一搜就发现这类产品特别的多，并且据闻各大公司都有自己的一套内部链路追踪系统，这下你可犯了大难。他们之间都是基于 Google Dapper 演进出来的，那本质上到底有什么区别，怎么延伸出这么多的新产品？

### Jaeger

首先看看由 Uber 开发的 Jaeger，Jaeger 目前由 Cloud Native Computing Foundation（CNCF）托管，是 CNCF 的第七个顶级项目（于 2019 年 10 月毕业）：

![image](https://image.eddycjy.com/1a672c2972602f1f154c1666c94e860a.png)

- Jaeger Client：Jaeger 客户端，是 Jaeger 针对 OpenTracing API 的特定语言实现，可用于手动或通过与 OpenTracing 集成的各种现有开源框架（例如Flask，Dropwizard，gRPC等）来检测应用程序以进行分布式跟踪。

- Jaeger Agent：Jaeger 客户端代理，在 UDP 端口上监听所接受的跨度并将其分批发送给 Collector。

- Jaeger Collector：Jaeger 收集器，顾名思义是面向 Agent，用于收集/管理链路的追踪信息。

- Jaeger Query：数据查询与前端界面展示。

- Jaeger Ingester：可从 Kafka 读取数据并写入其他的存储介质（Cassandra，Elasticsearch）。

在了解 Jaeger 的各组件功能后，主要关注其整体的整体架构上的数据流转：

![image](https://image.eddycjy.com/3d954d769e4e21c998c31336996d1a00.jpg)

Jaeger 是一个很经典的架构，由客户端主动发送链路信息到 Agent，Agent 上报给 Collector，再经由队列，最终落地到存储。再由另外的可视化管理后台进行查看和分析。

更具现化就是 上报 =》收集 =》存储 =》分析的标准化流程。并且你会发现 Jaeger 与 Zipkin 在架构上差不多：

![image](https://image.eddycjy.com/d694663f68fc1ed6bd8a467b2e49d958.png)

- Zipkin Collector：Zipkin 收集器，用于收集/管理链路的追踪信息。

- Storage：Zipkin 数据存储，支持 Cassandra、ElasticSearch 和 MySQL 等第三方存储。

- Zipkin Query Service：数据存储并建立索引后，用于查找和检索跟踪信息。

- Web UI：数据查询与前端界面展示。

从时间上来看 Jaeger 比 Zipkin 晚四年，莫非是重复造轮子。经过翻阅，可得知做 Jaeger 的主要原因是：
> 当时将跨度发送到 Zipkin 的唯一方法是通过 Scribe，而 Zipkin 支持的唯一高性能数据存储是 Cassandra。当时 Uber 对这两种技术都没有经验，因此选择了自己构建一个后端，该后端将一些自定义组件与 Zipkin UI 结合在一起，形成了一个完整的跟踪系统。

更详细可阅读 [Evolving Distributed Tracing at Uber Engineering](https://eng.uber.com/distributed-tracing/)，可以了解很多细节。

### 阿里鹰眼

链路追踪系统的另一代表，基于日志和流式计算去做的居多，像是阿里的鹰眼，滴滴的 traces，如下图：

![image](http://5b0988e595225.cdn.sohucs.com/images/20171007/2ba764f2df1e453998ae58ac852483ee.jpeg)

更具体可见[《阿里巴巴鹰眼技术解密》](https://myslide.cn/slides/696) 和 [《异构系统链路追踪——滴滴 trace 实践》](https://www.itdks.com/Home/Course/detail?id=3658) 在大会上的分享，这里就不再赘述了，推荐好奇或忧愁链路追踪落地的小伙伴们阅读。

## 总结

大多数在初始选型时都会选择亲和性比较强的追踪系统，就像是 Jaeger 属于 Go，Zipkin、Skywalking 是 Java 系居多，三者都完全兼容 OpenTracing，只是架构上多少有些不同，且都是基于 Google Dapper 发散，因此所支持的基本功能和查询页面优雅与否很重要。

而本来就有原始的 N 个系统，如果想接入直接新的链路追踪系统，还是非常麻烦的。因为原意想接入，必然是想解决原有系统的排查/定位问题，而不单单是为了新系统，因此单从接入的角度来讲，大多不会就不会使用既有开源追踪系统（除非历史债务不大），且数据量可能极大。

因此基于既有方法去改造来清洗数据再做成链路追踪的模式也挺常见的，这之中日志常常是一个比较好的下手点，也就是去清洗某某数据，形成新的分析系统，再造一个内部轮子。

另外近两年基于 ServiceMesh 的 ”无” 侵入式链路追踪也广受欢迎，似乎是一个被看好的方向，其代表作之一 Istio 便是使用 CNCF 出身的 Jaeger，且 Jaeger 还兼容 Zipkin，在这点上 Jaeger 完胜。

================================================
FILE: content/posts/mq-nodus.md
================================================
---
title: "《漫谈 MQ》设计 MQ 的 3 个难点"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - mq
---


大家好，我是煎鱼。

前段时间我们分享了漫谈 MQ 的第一期《要消息队列（MQ）有什么用？》，感觉打开了一个新的世界。

但很快就有小伙伴意识到了不妙，既然 MQ 承接了多个系统，那岂不是该有的问题，他都有，又或是更甚。如下：

![](https://files.mdnice.com/user/3610/45b00332-9a06-49b6-a666-675890409c94.png)

今天我们就进一步讲讲，**设计 MQ 时很有可能会遇到的几个大难点**，在业内又配套用了什么解决方案去处理。

## 几个难点

从结论上来看，设计 MQ 这一个存在。会至少引发三大难点。堪称互联网经典的，也是面试官们最爱问的：
- 高可用：代表系统的可用性程度，高可用性通常通过提高系统的容错能力来实现，从而减少系统宕机时间。
- 高并发：代表通过设计保证系统能够同时并行处理很多请求，在同一个时间点，有很多用户同时访问同一系统、API、URL。
- 高可靠：代表能够满足预计条件的一个系统或组件（例如：备份、故障处理、数据存储以及访问），比较经典的是 4 个9 等标准。

### 高可用

像前面评论区留言的兄弟截图表述的一样。

虽然请求不直接找系统 A、B、C、D 了。但是请求都实打实的通过异步的方式打到了 MQ 上，就可以不断往 MQ 塞，变成了多个系统都在请求 MQ，可以认为压力比单系统同步调用大了不止一倍。

同时 MQ 还要去做消费关系的维护，存储既有和新增的大量消息。是一个既要也要还要的典型场景。

这样一来，新的一轮问题就出现了。就是要保证 MQ 的高可用，否则他轻轻松松就会被压到宕机，或是负载过高，出现一些匪夷所思的延迟。

如何保证 MQ 的高可用，是一个大问题。

### 高并发

在高并发上的诉求上，其实是和高可用的场景是一样的。既然各业务系统都是异步的了，自然他也就不会像同步阻塞一样 “等” 你。

像是我有一个朋友，他们喜欢批量清洗多租户的数据。业务程序也不怎么节制，几十、几百、上千万数据，利用 Go 语言写的，抄起 for-loop+go func 就是一把梭。刷刷刷一下子就就给打进 MQ 里。

再多来几个业务系统这么干，这 MQ 并发就比较高了，单单维护就是头疼。很有可能事故背着背着，年底就 3.25 了。因为 MQ，在业务中的依赖非常重，是标准的核心基础设施。

如何保证 MQ 能够承受高并发，是一个大问题。

### 高可靠

对 MQ 来讲，高可靠性的诉求，又分为好几个角度去理解。如下：
- 消息要靠谱：“我” 发的消息要能够可靠的到达 MQ，MQ 要能够正确的让消费者能够接收到推送或拉取。
- 存储要靠谱：“我” 发的消息，还在 MQ 上时要存储好，不能发到 MQ 上就因为大量数据，丢了。又或是查询很慢。
- 处理要靠谱：发了消息，可能会出现异常。发了消息，可能网络抖动，没有接收到。

上述我们列了三点 “要靠谱” 的内容。实质上，对于 MQ 来讲，其每一块领域都要保证其可靠性，否则查起问题来，真的是会非常崩溃。

甚至更往上，还会对 “高性能” 会有要求，不过这一块我们就不进一步展开了。

## 解决方案

### 核心流程

在清楚了设计 MQ 会遇到的三大难点后。我们需要先了解一下现代 MQ 的基础应用架构会是怎么样的。

MQ 包含如下三类角色：
- 生产者（Producer）：负责生产消息。
- 消费者（Consumer）：负责消费消息。
- 服务端（Broker）：负责存储和处理消息，是 MQ 的核心部分。由队列（Queue）延伸而来，因为功能已经不仅仅局限于队列属性了。

其核心流程如下：

![核心流程](https://image.eddycjy.com/7b729b7d25ab9f52205008b3ee63dae7.jpg)

1. 生产者（Producer）发送消息到达服务端（Broker），服务端进行消息存储，核心逻辑处理等。
2. 再根据先前注册消费的关系（例如：订阅），进行消息的推送或被拉取。也就是消费消息了。
3. 在完成消费消息后再返回确认（ACK）给服务端。若出现一定时间内未收到 ACK，则会触发服务端的重试机制。
4. 服务端确定消息处理完毕，删除消息和进行记录。

### 对三高下手

#### 设计高可用

在高可用上，主要要针对服务端（Broker）来做。目前常见的是保证服务端可以进行水平扩展，能够做跨集群的部署。

因此相应上得配套做服务的注册和发现机制，负载均衡（确保服务端压力均衡）。以此来构成 MQ 高可用的基本维持。

#### 设计高并发

在高并发上，服务端必然包含队列（Queue），会起到缓冲的作用。但仍然可能会出现单点流量过大。

因此通常会结合像是 RocketMQ 的 Topic，Kafka 的 Partition 等做队列划分，起到分而治之的作用。

#### 设计高可靠

在高可靠上，主要是针对消息发送、存储消息、处理消息这三块进行展开。

消息发送上，会结合 SDK 和服务端两者，发送和消费消息的确认（ACK）机制、重试机制等来实现消息的可靠性。

存储消息上，常见分为：分布式缓存、分布式文件系统、数据库方案等。目前主流的话，会采取落盘的方式，也就是将消息主体追加写入到日志文件，再配合索引文件来做快速的消息查找。

和 MySQL 数据库的存储模式是有一定的神似之处。

## 总结

在今天这篇文章中，我们面向设计 MQ 中常见的 3 大难点（其实还有更多，以后再介绍...）进行了逐一介绍和说明。同时也针对业内常见的解决方案进行了剖析。

在我们了解了这些细节后，在真正应用 MQ 时，就不会感到那么的无奈。因为常常你所遇到的，消息丢失，又或是消息重试导致裂变所导致宕机。

往往都来自于你所忽略的这些设计细节之中。即使对到用户端上只是几个简单的配置，你也应当理解这些知识 ：）

================================================
FILE: content/posts/prometheus/2020-05-16-metrics.md
================================================
---
title: "Prometheus 四大度量指标的了解和应用"
date: 2020-05-16T15:08:51+08:00
toc: true
tags: 
  - prometheus
---

在上一个章节中我们完成了 Prometheus 的基本概念了解和安装，由于考虑到看我博客的估计是开发向的小伙伴居多，因此没有再更深入。而今天本章节将介绍我们开发用的最多的度量指标，并结合实战对 Metrics 进行使用和细节分析。

## 什么是度量指标

> 来自维基百科

度量是指对于一个物体或是事件的某个性质给予一个数字，使其可以和其他物体或是事件的相同性质比较。度量可以是对一物理量（如长度、尺寸或容量等）的估计或测定，也可以是其他较抽象的特质。

简单来讲，也就是数据的量化，形成对应的数据指标。

## Prometheus 的指标格式

在 Prometheus 中，我们的指标表示格式如下：

```
<metric name>{<label name>=<label value>, ...}
```

主体为指标名称和标签组成：

```
api_http_requests_total{method="POST", handler="/eddycjy"}
```

## 对外提供 metrics 服务

首先创建一个示例项目：

```go
func main() {
    engine := gin.New()
    engine.GET("/hello", func(c *gin.Context) {
        c.String(http.StatusOK, "煎鱼")
    })
    engine.Run(":10001")
}
```

接下我们需要安装 Prometheus Client SDK，在 Go 语言中对应 [prometheus/client_golang](https://github.com/prometheus/client_golang) 库：

```shell
$ go get github.com/prometheus/client_golang
```

然后调用 `promhttp.Handler` 方法创建对应的 metrics：

```go
func main() {
    ...
    engine.GET("/metrics", gin.WrapH(promhttp.Handler()))
    engine.Run(":10001")
}
```

重新启动程序，并访问 `http://127.0.0.1:10001/metrics`：

```shell
# HELP go_gc_duration_seconds A summary of the pause duration of garbage collection cycles.
# TYPE go_gc_duration_seconds summary
go_gc_duration_seconds{quantile="0"} 0
go_gc_duration_seconds{quantile="0.25"} 0
go_gc_duration_seconds{quantile="0.5"} 0
go_gc_duration_seconds{quantile="0.75"} 0
go_gc_duration_seconds{quantile="1"} 0
go_gc_duration_seconds_sum 0
go_gc_duration_seconds_count 0
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 8
# HELP go_info Information about the Go environment.
# TYPE go_info gauge
go_info{version="go1.14.2"} 1
# HELP go_memstats_alloc_bytes Number of bytes allocated and still in use.
# TYPE go_memstats_alloc_bytes gauge
go_memstats_alloc_bytes 2.563056e+06
...
```

我们可以聚焦其中一个指标：

```
# HELP go_goroutines Number of goroutines that currently exist.
# TYPE go_goroutines gauge
go_goroutines 8
```

你会发现其具有固定的表示格式，分别是指标的含义、指标的类型、指标的具体字段和数值。而在 `promhttp.Handler` 方法所暴露出来的 metrics 数值，虽然看似很多，但你认真看一下，可以主体为两块：

1. go_memstats 开头的指标都是 [runtime.MemStats](https://golang.org/pkg/runtime/#MemStats) 的格式化数值。

2. promhttp_metric 开头的指标是 HTTP 服务的状态码统计。


## Prometheus 四大度量指标的了解和应用

### Counter（计数器）

Counter 类型代表一个累积的指标数据，其单调递增，只增不减。在应用场景中，像是请求次数、错误数量等等，就非常适合用 Counter 来做指标类型，另外 Counter 类型，只有在被采集端重新启动时才会归零。

Counter 类型一共包含两个常规方法，如下：

方法名 | 作用
---|---
Inc | 将计数器递增 1。
Add(float64) | 将给定值添加到计数器，如果设置的值 < 0，则发生错误。

#### 实战演练

Counter 类型是单纯的累积类计数，最基础的就是在访问请求的时候进行分类统计，在上文的示例项目中继续添加代码：

```go
var AccessCounter = prometheus.NewCounterVec(
    prometheus.CounterOpts{
        Name: "api_requests_total",
    },
    []string{"method", "path"},
)

func init() {
    prometheus.MustRegister(AccessCounter)
}

func main() {
    ...
    engine.GET("/counter", func(c *gin.Context) {
        purl, _ := url.Parse(c.Request.RequestURI)
        AccessCounter.With(prometheus.Labels{
            "method": c.Request.Method,
            "path":   purl.Path,
        }).Add(1)
    })
    engine.GET("/metrics", gin.WrapH(promhttp.Handler()))
    engine.Run(":10001")
}
```

这时候我们访问 `http://127.0.0.1:10001/counter`，就可以发现 metrics +1：

```
# HELP api_requests_total 
# TYPE api_requests_total counter
api_requests_total{method="GET",path="/counter"} 1
```

如果希望对全部请求进行记录和统计，我们可以利用拦截器来实现，但是在添加 Labels 时需要注意一点，就是你所定义的指标 Labels 和实际写入时的 Labels 要对应，否则会造成 panic：

```
2020/05/17 11:01:06 http: panic serving 127.0.0.1:53393: inconsistent label cardinality: expected 3 label values but got 2 in prometheus.Labels{"method":"GET", "path":"/hello"}
goroutine 51 [running]:
net/http.(*conn).serve.func1(0xc0000ee000)
        /usr/local/Cellar/go/1.14.2_1/libexec/src/net/http/server.go:1772 +0x139
panic(0x16272a0, 0xc00009c130)
        /usr/local/Cellar/go/1.14.2_1/libexec/src/runtime/panic.go:975 +0x3e3
github.com/prometheus/client_golang/prometheus.(*CounterVec).With(0xc0001347e0, 0xc00009a4e0, 0x16ea903, 0x4)
        /Users/eddycjy/go/pkg/mod/github.com/prometheus/client_golang@v1.6.0/prometheus/counter.go:259 +0xc2

```

### Gauge（仪表盘）

Gauge 类型代表一个可以任意变化的指标数据，其可增可减。在应用场景中，像是 Go 应用程序运行时的 Goroutine 的数量就可以用该类型来表示，因为其是浮动的数值，并非固定的，侧重于反馈当前的情况。

Gauge 类型一共包含六个常规方法，如下：

方法名 | 作用
---|---
Set(float64) | 将仪表设置为任意值。
Inc() | 将仪表增加 1。
Dec() | 将仪表减少 1。
Add(float64) | 将给定值添加到仪表，该值如果为负数，那么将导致仪表值减少。
Sub(float64) | 从仪表中减去给定值，该值如果为负数，那么将导致仪表值增加。
SetToCurrentTime() | 将仪表设置为当前Unix时间（以秒为单位）。

#### 实战演练

Gauge 类型是每次都重新设置的统计类型，在系统中统计 CPU、Memory 等等时很常见，而在业务场景中，业务队列的数量也可以用 Gauge 来统计，实时观察队列数量，及时发现堆积情况：

```go
var QueueGauge = prometheus.NewGaugeVec(
    prometheus.GaugeOpts{
        Name: "queue_num_total",
    },
	[]string{"name"},
)

func init() {
    prometheus.MustRegister(AccessCounter)
}

func main() {
    ...
    engine.GET("/queue", func(c *gin.Context) {
        num := c.Query("num")
        fnum, _ := strconv.ParseFloat(num, 32)
        QueueGauge.With(prometheus.Labels{"name": "queue_eddycjy"}).Set(fnum)
    })
    engine.GET("/metrics", gin.WrapH(promhttp.Handler()))
    engine.Run(":10001")
}
```

访问 `http://127.0.0.1:10001/queue?num=5` 后，再查看 metrics 结果：

```
# HELP queue_num_total 
# TYPE queue_num_total gauge
queue_num_total{name="queue_eddycjy"} 5
```

另外 Gauge 类型也支持各种增减方法，大家根据实际情况调用即可。 

### Histogram（累积直方图）

Histogram 类型将会在一段时间范围内对数据进行采样（通常是请求持续时间或响应大小等等），并将其计入可配置的存储桶（bucket）中，后续可通过指定区间筛选样本，也可以统计样本总数。

简单来讲，也就是在配置 Histogram 类型时，我们会设置分组区间，例如要分析请求的响应时间，我们可以分为 0-100ms，100-500ms，500-1000ms 等等区间段，那么在 metrics 的上报接口中，将会分为多个维度显示统计情况。

Histogram 类型一共包含一个常规方法，如下：

方法名 | 作用
---|---
Observe(float64) | 将一个观察值添加到直方图。

#### 实战演练

Histogram 类型在应用场景中非常的常用，因为其代表的就是分组区间的统计，而在分布式场景盛行的现在，链路追踪系统是必不可少的，那么针对不同的链路的分析统计就非常的有必要，例如像是对 RPC、SQL、HTTP、Redis 的 P90、P95、P99 进行计算统计，并且更进一步的做告警，就能够及时的发现应用链路缓慢，进而发现和减少第三方系统的影响。

我们模仿记录 HTTP 调用响应时间的应用场景：

```go
var HttpDurationsHistogram = prometheus.NewHistogramVec(
    prometheus.HistogramOpts{
        Name:    "http_durations_histogram_seconds",
        Buckets: []float64{0.2, 0.5, 1, 2, 5, 10, 30},
    },
    []string{"path"},
)

func init() {
    prometheus.MustRegister(HttpDurationsHistogram)
}

func main() {
	...
    engine.GET("/histogram", func(c *gin.Context) {
        purl, _ := url.Parse(c.Request.RequestURI)
        HttpDurationsHistogram.With(prometheus.Labels{"path": purl.Path}).Observe(float64(rand.Intn(30)))
    })
    engine.GET("/metrics", gin.WrapH(promhttp.Handler()))
    engine.Run(":10001")
}
```

多次调用 `http://127.0.0.1:10001/histogram`，查看 metrics：

```
# HELP http_durations_histogram_seconds 
# TYPE http_durations_histogram_seconds histogram
http_durations_histogram_seconds_bucket{path="/histogram",le="0.2"} 1
http_durations_histogram_seconds_bucket{path="/histogram",le="0.5"} 1
http_durations_histogram_seconds_bucket{path="/histogram",le="1"} 3
http_durations_histogram_seconds_bucket{path="/histogram",le="2"} 3
http_durations_histogram_seconds_bucket{path="/histogram",le="5"} 3
http_durations_histogram_seconds_bucket{path="/histogram",le="10"} 3
http_durations_histogram_seconds_bucket{path="/histogram",le="30"} 13
http_durations_histogram_seconds_bucket{path="/histogram",le="+Inf"} 13
http_durations_histogram_seconds_sum{path="/histogram"} 191
http_durations_histogram_seconds_count{path="/histogram"} 13
```

我们结合 histogram metrics 的结果来看，可以发现其分为了三个部分：

1. http_durations_histogram_seconds_bucket：在 Buckets 中你可以发现一共包含 8 个值，分别代表：0-0.2s、0.2-0.5s、0.5-1s、1-2s、2-5s、5-10s、10-30s 以及大于 30s（+Inf），这是我们在 `HistogramOpts.Buckets` 中所定义的区间值。

2. http_durations_histogram_seconds_sum：调用的总耗时。

3. http_durations_histogram_seconds_count：调用总次数。

Histogram 是一个比较精巧类型，首先 Buckets 的分布区间要根据你的实际应用情况，合理的设置，否则就会出现不均，自然而然 PXX（P95、P99 等）计算也就会有问题，同时在 Grafana 上的绘图也会出现偏差，因此需要在理论上多多理解，然后再进行具体的设置，否则后期改来改去会比较麻烦

同时我们也可以利用 http_durations_histogram_seconds_sum 和 http_durations_histogram_seconds_count 相除得出平均耗时，一举多得。

### Summary（摘要）

Summary 类型将会在一段时间范围内对数据进行采样，但是与 Histogram 类型不同的是 Summary 类型将会存储分位数（在客户端进行计算），而不像 Histogram 类型，根据所设置的区间情况统计存储。 

Summary 类型在采样计算后，一共提供三种摘要指标，如下：

- 样本值的分位数分布情况。
- 所有样本值的大小总和。
- 样本总数。

Summary 类型一共包含一个常规方法，如下：

方法名 | 作用
---|---
Observe(float64) | 将一个观察值添加到摘要。

#### 实战演练

Summary 类型主要是

```go
var HttpDurations = prometheus.NewSummaryVec(
    prometheus.SummaryOpts{
        Name:       "http_durations_seconds",
        Objectives: map[float64]float64{0.5: 0.05, 0.9: 0.01, 0.99: 0.001},
    },
    []string{"path"},
)

func init() {
    prometheus.MustRegister(HttpDurations)
}

func main() {
    ...
    engine.GET("/summary", func(c *gin.Context) {
        purl, _ := url.Parse(c.Request.RequestURI)
        HttpDurations.With(prometheus.Labels{"path": purl.Path}).Observe(float64(rand.Intn(30)))
    })
    engine.GET("/metrics", gin.WrapH(promhttp.Handler()))
    engine.Run(":10001")
}
```

多次调用 `http://127.0.0.1:10001/summary`，查看 metrics：

```
# HELP http_durations_seconds 
# TYPE http_durations_seconds summary
http_durations_seconds{path="/summary",quantile="0.5"} 17
http_durations_seconds{path="/summary",quantile="0.9"} 29
http_durations_seconds{path="/summary",quantile="0.99"} 29
http_durations_seconds_sum{path="/summary"} 85
http_durations_seconds_count{path="/summary"} 5
```

结合 summary metrics 来看，同样分为了三个部分：

1. http_durations_seconds：分别是中位数（0.5），9 分位数（0.9）以及 99 分位数（0.99），对应 `SummaryOpts.Objectives` 中我们所定义的中位数，而各自的意义代表着中位数（0.5）的耗时为 17s，9 分位数为 29s，99 分位数为 29s。

2. http_durations_seconds_sum：调用总耗时。

3. http_durations_seconds_count：调用总次数。

## 小结

在本章节中我们介绍并实操了 Prometheus 的四种度量指标类型 Counter、Gauge、Histogram、Summary，这四种度量类型都极具代表性：Counter 是单调递增的计数器，Gauge 是可任意调整数值的仪表盘，Histogram 是分组区间统计，Summary 是中位数统计。

其中 Histogram 和 Summary 具有一定的 “相似” 度，因为在 Histogram 指标中我们可以通过 `histogram_quantile` 函数计算出分位值，而 Summary 也可以计算分位值，两者区别就在于 Histogram 是在服务端计算的，而 Summary 是在客户端就进行了计算，其一个计算好了再推上去，一个直接推上去，数据维度不一样，可以做的事情也不一样，有利有弊，具体可以根据指标的实际情况做衡量。


另外针对度量指标的命名，这是一个非常多人问的问题，因为命名是一个难题，在这里大家可以参照官方的[文档](https://prometheus.io/docs/practices/naming/)建议去针对指标命名就可以了。




================================================
FILE: content/posts/prometheus/2020-05-16-pull.md
================================================
---
title: "使用 Prometheus 对 Go 程序进行指标采集"
date: 2020-05-17T17:52:37+08:00
---

在前面的章节中，已经知道了如何对应用程序进行 Prometheus metrics 的注册和暴露，那么接下来如何让 Prometheus 对应用程序进行采集呢。

## 设置采集配置

首先打开先前所安装的 prometheus 软件目录：

```sh
$ ls
LICENSE                data                   promtool
NOTICE                 prometheus             rules
console_libraries      prometheus.yml         tsdb
consoles               prometheus.yml.default
```

打开并修改 prometheus.yml 文件，查看到 [scrape_configs](https://prometheus.io/docs/prometheus/latest/configuration/configuration/#scrape_config) 配置选项，进行如下调整：

```sh
...
scrape_configs:
  - job_name: 'test01'
    static_configs:
    - targets: ['127.0.0.1:10001']
    scheme: http
    tls_config:
        insecure_skip_verify: false
```

先前所启动的应用程序是在本地，且端口号为 10001，协议为 http，对应的配置简述：

- job_name：采集的任务名。

- static_configs.targets：设置要采集的目标对象列表。

- scheme：采集的目标协议（例如：http、https）。

- tls_config.insecure_skip_verify：是否跳过证书校验。

常用的配置项如上几个，其默认的 metrics path 为 `/metrics`，若需要调整则增加 metrics_path 配置项进行调整就可以了，接着重新启动 prometheus 就可以了。

## 其他配置项

再返回来看看 prometheus.yaml 文件：

```
global:
  scrape_interval:     15s 
  evaluation_interval: 15s


alerting:
  alertmanagers:
  - static_configs:
    - targets:
       - localhost:9093

rule_files:
   - ../rules/*.yaml

scrape_configs:
  - job_name: 'test01'
    static_configs:
    - targets: ['127.0.0.1:10001']
    scheme: http
    tls_config:
        insecure_skip_verify: false
```

- scrape_interval：采集间隔（频率）。

- evaluation_interval：规则计算间隔（频率）。

- alerting.alertmanagers：此 prometheus 所计算的 rules 所对应的 alertmanager。

- rule_files：此 prometheus 所对应的告警规则（rules）。

这里聚焦 rule_files 和 alertmanagers，其分别对应着后续章节所要学的告警规则编写和 alertmanager 的告警平台对接和使用，留个心眼即可。

## 重新启动 Prometheus

在启动 prometheus 时，可以根据自己的情况进行一些启动项的调整：

```
$ ./prometheus --web.listen-address="0.0.0.0:9091" --config.file="prometheus.yml" 
```

在上述语句中，`--web.listen-address` 调整启动的监听 HOST+PORT，`--config.file` 调整 prometheus 启动时所读取的配置文件地址，更多的可以执行 `./prometheus --help` 命令进行查看。

## 查看采集情况

在完成配置后，在经过 scrape_interval 秒后，将会自动采集到 prometheus 上，就可以在 Console 上进行查看：

![image](https://image.eddycjy.com/958dd2950b64c2a10a73b03864b0e153.jpg)

若想要简单查看趋势，也可以通过 Graph 进行趋势分析：

![image](https://image.eddycjy.com/13e83b57dde665ffbbea8456efd0b146.jpg)

但长久来看，还是建议使用 Grafana（后续会进行讲解）。

## 总结

至此就完成了一个 Prometheus 对 Go 应用程序的基本采集，本章节主要是熟悉 Prometheus 拉模式的采集机制，以及对应的 Promtheus 规则编写和使用即可，虽然比较很简单，但是这块内容的知识体系的了解程度是后面所有内容的基石，建议根据[官方文档](https://prometheus.io/docs/introduction/overview/)再进一步的学习。




================================================
FILE: content/posts/prometheus/2020-05-16-startup.md
================================================
---
title: "Prometheus 快速入门"
date: 2020-05-16T12:05:58+08:00
toc: true
tags: 
  - prometheus
---

一般我们说 Prometheus，有两种理解，我们平时需要注意识别的，其含义有两种，一是指的 Prometheus 自身，是一个时序数据库；另外一种是指 Prometheus 生态圈，指的是是整体的监控报警的生态圈和解决方案（Prometheus+Grafana+Alertmanager）。

Prometheus 在 2016年加入了 CNCF（Cloud Native Computing Foundation），是继 Kubernetes 之后的第二个托管项目，目前已经毕业，其主要的特点如下：

- 多维度的数据模型：由指标名称和键/值对标签标识的时间序列数据来组成多维的数据模型。
- 灵活的查询语言：在 Prometheus 中使用强大的查询语言 PromSQL 来进行查询。
- 不依赖分布式存储，Prometheus 单个节点也可以直接工作，支持本地存储（TSDB）和远程存储的模式。
- 服务端采集数据：Prometheus 基于 HTTP pull 方式去对不同的端采集时间序列数据。
- 客户端主动推送：支持通过 PushGateway 组件主动推送时间序列数据。

## Prometheus 生态组件

Prometheus 生态由多个组件共同组成，其中许多组件是可根据实际情况选择的，并且绝大部分由 Go 语言编写，在部署和构建上比较方便，如下：

- Prometheus Server：[Prometheus 服务端](https://github.com/prometheus/prometheus)，用于收集指标和存储时间序列数据，并提供一系列的查询和设置接口。
- Client Libraries：[客户端库](https://prometheus.io/docs/instrumenting/clientlibs/)，用于帮助需要监控采集的服务暴露 metrics handler 给 Prometheus server。例如像 [例子](https://github.com/prometheus/client_golang/blob/master/examples/simple/main.go) 中直接调用 promhttp 暴露了一个 metrics 接口。
- Push Gateway：推送网关，Prometheus 服务端仅支持 HTTP pull 的采集方式，而有一些指存在的时间短，Prometheus 来 pull 前就结束了。又或是该类指标，就是要客户端自行上报的，这时候就可以采用 Push Gateway 的方式，客户端将指标 push 到 Push Gateway，再由 Prometheus Server 从 Pushgateway 上 pull。
- Exporters：用于暴露已有的第三方服务（HAProxy，StatsD，Graphite）的 metrics 给 Prometheus Server。
- Alertmanager：用于处理告警，从 Prometheus server 端接收到 alerts 后，会进行去重，分组，然后路由到对应的Receiver，发出报警。
- Support Tools：各种支持工具。

## Prometheus 整体流程图

Prometheus 的整体架构和生态组件组成，如下图所示：

![image](https://prometheus.io/assets/architecture.png)

Prometheus Server 通过从监控目标中或者间接通过推送网关来拉取监控指标，它在本地存储所有抓取到的样本数据，并对此数据执行一系列规则，以汇总和记录现有数据的新时间序列或生成告警。可以通过 Grafana 或者其他工具来实现监控数据的可视化。

## Prometheus 采集的数据存到哪里

Prometheus 所有采集的指标数据在默认的情况下，都保存在本地所内置的时间序列数据库（TSDB）当中，如果需要另外调整，再将 Prometheus 的存储指向改为远程存储即可。

Prometheus 采用在默认情况下使用本地存储，能够一定的便利性，例如：开箱即用、运维方便（不用管）等等。但是也有不少缺点，像是海量数据无法持久化等等问题，因此强烈建议在上到企业级的海量应用时，一定对其进行研讨，适当考虑远程存储。

### 时序数据库是什么

Prometheus 是时序数据库（Time Series Database），又简称 TSDB。目前在行业中比较出名，流行度较高的时序数据库如下：

![image](https://image.eddycjy.com/899042452628900ef32fe11f8d7a4b1e.jpg)

时序数据库简单来讲，就是将数据按照时间顺序排列，它具有唯一性和可排序性，因此在 Prometheus 的 Metrics 中即使只添加了一个新标签，也会造成破坏，也就是它不再是原本的那个时序数据了。

注：时序数据库是一个比较大的话题，后续会单独开一篇文章讲解，此处仅概要。

### Prometheus 远程存储的方案

- AppOptics: write
- Azure Data Explorer: read and write
- Chronix: write
- Cortex: read and write
- CrateDB: read and write
- Elasticsearch: write
- Gnocchi: write
- Graphite: write
- InfluxDB: read and write
- IRONdb: read and write
- Kafka: write
- M3DB: read and write
- OpenTSDB: write
- PostgreSQL/TimescaleDB: read and write
- QuasarDB: read and write
- SignalFx: write
- Splunk: read and write
- TiKV: read and write
- Thanos: write
- VictoriaMetrics: write
- Wavefront: write

### 数据持久化的意义

- 数据存储与服务提供应当隔离。
- 事故、问题的度量指标回溯。
- 数据挖掘的考虑。
- 提供给外部的自定义平台进行数据查询等等
- ...


## 安装 Prometheus

[Prometheus](https://github.com/prometheus/prometheus) 是由 Go 语言编写的，因此安装非常的方便，只需要在 [DOWNLOAD](https://prometheus.io/download/) 中下载对应的 tar.gz 文件。进行如下解压：

```
$ tar xvfz prometheus-*.tar.gz
```

就可以看到下述目录：

```
prometheus
├── LICENSE
├── NOTICE
├── console_libraries
├── consoles
├── data
├── prometheus
├── prometheus.yml
├── prometheus.yml.default
├── promtool
├── rules
└── tsdb
```

启动 Prometheus：

```
$ ./prometheus 
...
level=info ts=2020-05-16T07:33:34.138Z caller=main.go:661 msg="Starting TSDB ..."
level=info ts=2020-05-16T07:33:34.139Z caller=web.go:508 component=web msg="Start listening for connections" address=0.0.0.0:9090
```

默认监听 9090 端口：

![image](https://image.eddycjy.com/f39b6b6f1c195973285d2bfd690425f3.jpg)

至此我们就完成了 Prometheus 的基本启动了。

## 小结

在本章节中，我们快速了解 Prometheus 的基本概念和整体的生态概要，在下一章节起我们将进一步的实操，知行合一。

## 参考资料

- https://ryanyang.gitbook.io/prometheus/di-yi-zhang-jie-shao/overview
- https://www.cnblogs.com/xiangsikai/p/11288632.html
- https://www.cnblogs.com/charlieroro/p/8670959.html

================================================
FILE: content/posts/reading/2020-04-24-book.md
================================================
---
title: "2020年下半年：读书清单"
date: 2020-04-24T22:00:45+08:00
toc: false
images:
tags: 
  - 读书清单
---

2020 年的上半年因为一些事情耽搁了整体的进程，不过最近也快要到 Deadline 了，因此又愉快的能空出手了。

回顾这几年在个人技能上，我随着公司的大泥球应用再到微服务化的飞速发展，经历了很多，突破了更多，有了不少新的感悟。因此今年打算再修修内功，认识一下自己的弱小，所以读书清单会比较偏基础方向，如下：

## 必看

1. 《图解 TCP/IP》
2. 《TCP/IP 详解 卷1：协议》
3. 《深入理解计算机系统》
4. 《大话数据结构》
5. 《算法（第4版）》
6. 《剑指 Offer》
7. [《操作系统_清华大学》](https://www.bilibili.com/video/BV1js411b7vg)

## 可选

1. 《Unix 环境高级编程（第3版）》
2. 《SRE Google 运维解密》：进行中，已经了看了不少。
3. 《Google 工作法》：进行中，已经了看了不少。

所有的目标都需要有一个验收的标准和奖罚，否则所谓的目标意义不会特别大。我想，**验收标准就是 [《重读 CS》](https://github.com/eddycjy/reread-cs-notes) 的基本成型**，其它不在该集合类的属于第二梯队，考虑释出读书笔记。

惩罚的话，发红包还是送书呢，先想想。


================================================
FILE: content/posts/reading/documentary-of-go.md
================================================
---
title: "Go: A Documentary 发布！"
date: 2020-09-11T20:46:38+08:00
toc: false
images:
tags: 
  - untagged
---

以前经常有读者问我，哪儿可以找到 Go 语言的前世今生，这种时候我们往往会告诉他去看 issues 和 proposals。但资料有点分散，且没有索引体系。因此不少人新入门的读者读着读着就跑偏了，又或是在第一步找资料上就被拦住了。

最近欧神（@changkun）低调的发布了 《Go: A Documentary》，这个文档收集了 Go 开发过程中许多有趣（公开可见的）的问题，讨论，提案，CL 和演讲，其目的是为 Go 历史提供全面的参考。

个人认为这份资料非常的有价值，相当于欧神把资料索引整理好了，强烈推荐对 Go 语言感兴趣的读者进行阅读：

![image](https://image.eddycjy.com/0643ae29cdb8fb99d5a83bf67b443a9a.jpg)

内容索引主要分为：

- Sources
- Committers
    - Core Authors
    - Compiler/Runtime Team
    - Library/Tools/Security/Community
    - Group Interviews
- Timeline
- Language Design
    - Misc
    - Slice
    - Package Management (1.4, 1.5, 1.7)
    - Type alias (1.9)
    - Defer (1.13)
    - Error values (1.13)
    - Channel/Select
    - Generics
- Compiler Toolchain
    - Compiler
    - Linker
    - Debugger
    - Tracer
    - Builder
    - Modules
    - gopls
    - Testing
- Runtime Core
    - Statistics
    - Scheduler
    - Execution Stack
    - Memory Allocator
    - Garbage Collector
    - Memory model
    - ABI
- Standard Library
    - syscall
    - io
    - go/*
    - sync
    - Pool
    - Mutex
    - atomic
    - time
    - context
    - encoding
    - image, x/image
    - misc
- Unclassified But Relevant Links
- Fun Facts
- Acknowledgements

《Go: A Documentary》 的访问地址是 `https://golang.design/history/`，GitHub 仓库地址：`https://github.com/golang-design/history`，大家也可以通过 “阅读原文” 进入。


================================================
FILE: content/posts/reading/programmer-accom-base.md
================================================
---
title: "必知必会！计算机里一些基本又重要的概念"
date: 2020-10-17T00:25:59+08:00
toc: true
images:
tags: 
  - 程序员的自我修养
---

最近在翻阅文章时，看到全成推荐的《程序员的自我修养》，这是一本讲链接、装载与库的计算机图书，看了下目录后觉得挺有意思。

因此决定每读一章就将其读书笔记整理记录下来，分享给大家。

目录：

![image](https://image.eddycjy.com/bf202dccad8c3f8efb3726854b72e850.jpg)

## 不要让 CPU 打盹

在计算机发展早期，CPU 资源十分昂贵。如果一个 CPU 只能运行一个程序，那么当程序在读写磁盘（进行 I/O 操作）时，CPU 就空闲下来了。这在当时简直就是巨大的浪费。

![image](https://image.eddycjy.com/df419c04c95fc7d58cc6f6f34a2fb7fd.jpeg)

CPU 只能和一个程序A “聊天“，其他来再多的程序BCD，都没有任何操作的空间。就像早年的手机，打电话和上网（语音/数据）只能二选一，作为 CPU 的你，并不能多线程操作。

因此机智的人们很快就编写了一些监控程序，希望来解决这个问题。

### 多道程序（Multiprogramming）

多道程序起，操作系统正式具有同时运行多个程序的能力。

其是让 CPU 一次读取多个程序放入内存中。当某个程序暂时无须使用 CPU 时，监控程序就把另外的正在等待 CPU 资源的程序启动，以此使得 CPU 能够充分地利用起来。这种策略的确大大的提高了 CPU 资源的利用率。

#### 真实场景

你在 Windows 上点击鼠标 10 分钟以后系统才有反应，那是多么无奈的事情。因为没有优先级区分，自然一路排下来也就不知道要等到什么时候了，相当于半饿死。

#### 存在的问题

核心问题在于程序之间的调度策略太粗糙。对于多道程序来删，程序之间部分轻重缓急，也就是说不存在优先级的区分。因此如果有些程序急需使用 CPU 来完成一些任务，那么很有可能会很长时间后才有机会被分配到 CPU，才得以继续往下运行。

### 分时系统（Time-Sharing System）

程序运行模式改为协作的模式，在原有的多道程序继续升级改造，即每个程序运行一段时间以后都主动让出 CPU 给其他程序，使得一段时间内每个程序都有机会运行一小段。

#### 真实场景

比如你点击一下鼠标或按下一个键盘按键后，他会相较前者能够更快的得到响应，因为他好歹是存在切换的可能性。

#### 存在问题

这时候的监控程序已经比原有多道程序的模式已经复杂了不少，完整的操作系统雏形已经基本形成，很早期的 Windows（Windows 95 和 Windows NT 之前），MacOS X 之前的 MacOS 版本都是采用这种分时系统的方式来进行程序调度。

其仍然存在问题，核心在于若一个程序一直在进行一个耗时计算，便会一直霸占着 CPU 不放，那么操作系统也没有不放，就会导致其他程序都只能无限等待，相当于就是系统假死了。

### 多任务系统（Multi-tasking）

#### 背景

在分时系统中，一个程序死循环就会导致系统假死，并且其运行效率并不高，只能解决当时的交互式环境。

放在现在来讲，已经完全没法很好的运行。因此当时业界也在研究更为先进的操作系统模式，也就是现在最为流行也是最熟悉的多任务系统。

#### 解决方案

在多任务系统中，所有的应用程序都以进行（Process）的方式运行，其有以下特点：

- 每个进程都有自己独立的地址空间，因此各进程之间相互隔离。
- 每个 CPU 都由操作系统统一进行分配。
- 每个进程根据其优先级的高低都有机会得到 CPU。

但需要注意的是，若是进程运行超出了指定的时间，操作系统就会暂停该进程，将 CPU 资源分配给其他等待运行的进程。这种 CPU 的分配方式一般称作抢占式（Preemptive）。

通过这种方式，操作系统就可以强制剥夺 CPU 资源并且分配给它认为目前最需要资源的进程，如果分配给每个进程的时间都很短，即 CPU 在多个进程间快速切换，就可以造成多个进程同时在运行的假象。

## 内存不够用怎么办

在早期的计算机中，程序是直接运行在物理内存上的，访问的内存地址都是物理地址。假设只是一个进程在跑，可能内存资源还够用，但实际上为了更有效地利用硬件资源，我们必须运行多个程序，CPU 的利用率才会比较高。这时候就会遇到一个严重的问题，那就是如何将计算机上有限的物理内存分配给多个程序使用？

![image](https://image.eddycjy.com/e029f8694bf3d0f79b9fe3e30451f141.jpg)

就像上图，每个程序他都想申请 1GB 的内容，而计算机本身只有 1GB 的物理内存，根本没有办法真正的执行。

### 真实场景和问题

可能会有小伙伴想，煎鱼你举的例子太极端了，我们举个 ”正常“ 点的例子。假设计算机有 128MB 内存，程序 A 运行需要 10MB，程序 B 需要 100MB，程序 C 需要 20 MB。假设该几个程序运行时，我们按照其想要的一分配，不就好了吗？

但现实并不是这样，这种简单的内存分配策略存在许多的问题：

- 地址空间不隔离：所有程序都直接访问物理地址，各程序所使用的内存空间并不是相互独立，很容易改写到其他程序的内存地址。

- 内存使用效率低：没有有效的内存管理机制，一会运行程序 A，一会运行程序 B，就需要经常要将大量数据换出换入，效率十分低下。

- 程序运行的地址不确定：每次程序运行时，都需要从内存中给其分配一块足够大的空闲区域，但这些内存区域位置是不确定的，给程序编写造成了一定的麻烦。

### 解决方法

解决上述问题的解决思路，就是万能的法宝：增加中间层，即使用一种间接的地址访问方法。把程序给出的地址看作是一种虚拟地址（Virtual Address），然后通过某些映射的方法，将这个虚拟地址最终转换成实际的物理地址。

上述提到了两个非常重要的内存概念：

- 物理地址空间：是实实在在存在的，存在于计算机中，且对每一台计算机来说只有唯一的一个，你可以将其想象为物理内存。

- 虚拟地址空间：是指虚拟的、人们想象出来的地址空间。其实它并不存在，每个进程都有自己的独立虚拟空间，且每个进程只能访问自己的地址空间。

如此一来，操作系统只需要控制虚拟地址到物理地址的映射过程，就可以保证任意一个程序锁你访问的物理内存区域和另外一个程序不重叠，以达到地址空间隔离的效果。

![进程虚拟空间、物理空间和磁盘之间的页映射关系](https://image.eddycjy.com/fb70d293e18832881e96330c2388614f.jpg)

另外需要清楚虚拟存储的实现需要依靠硬件的支持，对于不同的 CPU 来说不同。但大多采用 MMU（Memory Management Unit）的部件来进行页映射：

![虚拟地址到物理地址的转变](https://image.eddycjy.com/d1be0cd17fc6b36c54c9d33c95baae92.jpg)

CPU 发出的是虚拟地址（Virtual Address），也就是日常程序中所看到的是虚拟地址。经过 MMU 转换后就会变成物理地址（Physical Address）。

目前常见的 MMU 均已集成在 CPU 内部了，不会再以独立部件存在。

## 线程的那些事

线程（Thread），有时候被称为轻量级进程，是程序执行流程的最小单元。一个标准的线程由线程 ID、当前指令指针（PC）、寄存器集合和堆栈组成。

通常一个进程由一个到多个线程组成，各个线程之间共享程序的内存空间（包括代码段、数据段、堆等）及一些进程级的资源（如打开文件和信号）。

![image](https://image.eddycjy.com/1b00bbf5766fd7fb6f2c3fa68bdf7b38.jpg)

### 为什么需要多线程

- 某个操作可能会陷入长时间等待，等待的线程会进入睡眠状态，无法继续执行。多线程执行可以有效利用等待的时间。典型的例子是等待网络响应，这时候就可以切换了。

- 某个操作会消耗大量的时间，如果只有一个线程，程序和用户之间的交互会中断。多线程的情况下，可以让一个线程负责交互，另外一个线程负责计算。

- 程序逻辑本身就要求并发操作，例如一个多端下载软件。

- 多 CPU 或多核计算机，其本身就具备同时执行多个线程的能力。

- 相对于多进程应用，多线程在数据共享方面效率会高很多。

### 线程的访问权限

线程可以访问进程内存里的所有数据，甚至在知道堆栈地址的情况下，可以访问其他线程里的堆栈信息。其私有存储空间主要分为：栈、线程局部存储（Thread Local Storage，TLS）、寄存器（包括 PC 寄存器）。

### 线程调度和时间片

在单处理器对应多线程的情况下，并发是一种模拟处理的状态。操作系统会让这些多线程程序轮流执行，每次仅执行一小段时间（通常是几十到几百毫秒），这样子线程就 “看起来” 在同时执行。

不断在处理器上切换不同的线程行为称之为线程调度（Thread Schedule），通常拥有至少三种状态，分别是：

- 运行（Running）：此时线程正在执行。

- 就绪（Ready）：此时线程可以立刻运行，但 CPU 已经被占用，暂时无法分配。

- 等待（Waiting）：此时线程正在等待某一事件（例如：I/O 事件）发生，无法执行。

处于运行状态中的线程都会拥有一段可以执行的时间，这段时间段称为时间片（Time Slice）。其基本流转：

- 当时间片用尽的时候，进程进入就绪状态。

- 当时间片用尽之前，进程若开始等待某个事件，那么它将进入等待状态。

每当一个线程离开运行状态时，调度系统就会选择一个当前是就绪状态的线程继续执行。而一个处于等待状态的线程在完成所等待的事件后，就会进入就绪状态。

![image](https://image.eddycjy.com/b7cec2f55d30a4ed9d46f2d0e50387a7.jpg)

### 线程优先级

在 Windows 和 Linux 中，线程的优先级可以通过用户手动设置，系统也会根据线程的表现自动调整优先级，以使得调度更有效率。常见的一般有两类线程：

- IO 密集型线程（IO Bound Thread）：频繁等待，像是网络调用。

- CPU 密集型线程（CPU Bound Thread）：很少等待，主要是计算为主。

常见的线程调度方式如下：

- 轮转法：让各个线程轮流执行一小段时间，这也决定了线程之间存在交错执行的特点。

- 优先级调度：在具有优先级调度的系统中，线程都拥有各自的线程优先级，具有高优先级的线程会更早的执行，低优先级的线程常常要等待到系统中已经没有高优先级的可执行线程时才可以执行。

IO 密集型线程总是会比 CPU 密集型线程容易得到优先级的提升。但在优先级调度下，存在一种线程饿死的现象。一个线程被饿死，是说它的优先级比较低，在它执行之前，总是有较高优先级的线程要执行。因此低优先级线程始终无法执行。

为了避免饿死现象，调度系统会逐步提升那些等待了过长时间的得不到执行的线程优先级。这样的方式，一个线程只要等待足够长的时间，其优先级最终一定会提高到足够让他执行的程度。线程优先级改变一般有三种方式：

- 用户指定优先级。

- 根据进入等待状态的频繁程度提升或降低优先级。

- 长时间得不到执行而被提升优先级。

### 可抢占线程和不可抢占线程

线程在用尽时间片之后会被强制剥夺继续执行的权利，而进入就绪状态，这个过程叫做抢占（Preemption），即之后执行的别的线程抢占了当前线程。

目前以可抢占式线程居多，非抢占式线程在今日已经十分少见。

### 三种线程模型

日常在程序中使用的线程其实并不是内核线程，而是存在于用户态的用户线程。用户态并不一定在操作系统内核中对应同等数量的内核线程。接下来将介绍三种常见的用户态多线程库的实现方式。

#### 一对一模型

一对一模型指的是一个用户使用的线程就唯一对应一个内核使用的线程。

![一对一线程模型](https://image.eddycjy.com/af87eb0e79d373560bdbf4e7ed8ca630.jpg)

优点：

- 线程之间的并发是真正的并发。

- 线程阻塞时，其他线程执行不会受到影响。

缺点：

- 操作系统限制了内核线程的数量，因此一对一线程会让用户的线程数受限。

- 内核线程调度时，上下文切换的开销较大，导致用户线程的执行效率下降。

#### 多对一模型

多对一模型指的是多个用户线程映射到一个内核线程上，线程之间的切换由用户态的代码来进行。

![多对一模型](https://image.eddycjy.com/daf4659747a2f7edcc317493ec7ebf96.jpg)

优点：

- 线程切换相对于一对一模型来说高效许多。

缺点：

- 如果一个用户线程阻塞，那么所有的线程豆浆无法执行，因为内核线程也被阻塞住了。


#### 多对多模型

多对多模型指的是将多个用户线程映射到少数但不止一个内核线程上。

![多对多模型](https://image.eddycjy.com/25cdc9b99b8543ca33a6494b88e2d482.jpg)

优点：

- 一个用户线程阻塞，并不会导致其它用户线程也阻塞。

缺点：

- 性能提升不如一对一模型高。

## 总结

本文主要涉及到 CPU、内存、线程。我们能够从其的一些关注点知道为什么 CPU 调度会这样子发展，又经历了什么东西。内存为什么会出现虚拟内存，物理内存，其之间又是如何相互转换的。

另外还了解到线程的基本分类和常见调度方式等，这些都是计算机基本的软硬件知识，非常值得大家仔细思考。


================================================
FILE: content/posts/reading/programmer-compile-link.md
================================================
---
title: "应用编译，计算机中那些一定要掌握的知识细节"
date: 2020-10-28T20:52:52+08:00
toc: true
tags: 
  - 程序员的自我修养
---

”Hello World“ 程序几乎是每个程序员入门和开发环境测试的基本标准。代码如下：

```
#inclue <stdio.h>

int main()
{
	printf("Hello Wolrd\n");
	return 0;
}
```

编译该程序，再运行，就基本完成了所有新手的第一个程序。表面看起来轻轻松松，毫无悬念。但是实际上单纯这几下操作，就已经包含了不少暗操作。本着追根溯源的目的，我们将进一步对其流程进行分析。

![image](https://image.eddycjy.com/a8040c0fc18257d2891d4b570b02c44d.jpg)

其内部主要包含 4 个步骤，分别是：预处理、编译、汇编以及链接。由于篇幅问题本文主要涉及前三部分，链接部分将会放到下一篇文章来讲解。

## 预编译

程序编译的第一步是 “预编译” 环境。主要作用是处理源代码文件中以 ”#“ 开始的预编译指令，例如：`#include`、`#define` 等。

常见的处理规则是：

- 将所有 `#define` 删除，并且展开所有的宏定义。

- 处理所有条件预编译指令，比如 `if`、`ifdef`、`elif`、`else`、`endif`。

- 处理 `#include` 预编译指令，将所包含的文件插入到该预编译指令的位置（可递归处理子级引入）。

- 删除所有的注释。

- 添加行号和文件名标识，以便于编译时编译器产生调试用的行号信息及用于编译时产生编译错误或警告时显示行号。

- 保留所有的 `#pragma` 编译器指令，后续编译器将会使用。

在预编译后，文件中将不包含宏定义或引入。因为在预编译后将会全部展开，相应的代码段均已被插入文件中。像 Go 语言中的话，主要是 `go generate` 命令会涉及到相关的预编译处理。

## 编译

第二步正式进入到 "编译" 环境。主要作用是把预处理完的文件进行一系列词法分析、语法分析、语义分析及优化后生成相应的汇编代码文件。该部分通常是整个程序构建的核心部分，也是最复杂的部分之一。

执行编译操作的工具，一般称其为 “编译器”。编译器是将高级语言翻译成机器语言的一个工具。例如我们平时用 Go 语言写的程序，编译器就可以将其编译成机器可以执行的指令及数据。那么我们就不需要再去关心相关的底层细节，因为使用机器指令或汇编语言编写程序是一件十分费时及乏味的事情。

且高级语言能够使得程序员更关注程序逻辑的本身，不再需要过多的关注计算机本身的限制，具有更高的平台可移植性，能够在多种计算机架构下运行。

### 编译过程

编译过程一般分为 6 步：扫描、语法分析、语义分析、源代码优化、代码生成和目标代码优化。整个过程如下：

![image](https://image.eddycjy.com/c1e4902df20b68df654229d9618b9d58.jpg)

我们结合上图的源代码（Source Code）到最终目标代码（Final Target Code）的过程，以一段最简单的 Go 语言程序的代理例子来复现和讲述整个过程，如下：

```
package main

import (
	"fmt"
)

func main() {
	fmt.Println("Hello World.")
}
```

### 词法分析

首先 Go 程序会被输入到扫描器中，可以理解为所有解析程序的第一步，都是读取源代码。而扫描器的任务很简单，就是利用有限状态机对源代码的字符序列进行分割，最终变成一系列的记号（Token）。

如下 Hello World 利用 go/scanner 进行处理：

```
1:1     package "package"
1:9     IDENT   "main"
1:13    ;       "\n"
3:1     import  "import"
3:8     (       ""
4:2     STRING  "\"fmt\""
4:7     ;       "\n"
5:1     )       ""
5:2     ;       "\n"
7:1     func    "func"
7:6     IDENT   "main"
7:10    (       ""
7:11    )       ""
7:13    {       ""
8:2     IDENT   "fmt"
8:5     .       ""
8:6     IDENT   "Println"
8:13    (       ""
8:14    STRING  "\"Hello World.\""
8:28    )       ""
8:29    ;       "\n"
9:1     }       ""
9:2     ;       "\n"
```

在经过扫描器的扫描后，可以看到输出了一大堆的 Token。如果没有前置知识的情况下，第一眼可能会非常懵逼。在此可以初步了解一下 Go 所主要包含的标识符和基本类型，如下：

```
	// Special tokens
	ILLEGAL Token = iota
	EOF
	COMMENT

	// Identifiers and basic type literals
	// (these tokens stand for classes of literals)
	IDENT  // main
	INT    // 12345
	FLOAT  // 123.45
	IMAG   // 123.45i
	CHAR   // 'a'
	STRING // "abc"
	literal_end
```

再根据所输出的 Token 稍加思考，做对比，就可得知其仅是单纯的利用扫描器翻译和输出。而实质上在识别记号时，扫描器也会完成其他工作，例如把标识符放到符号表，将数字、字符串常量存放到文字表等。

词法分析产生的记号一般可以分为如下几类：

- 关键字。

- 标识符。

- 字面量（包含数字、字符串等）。

- 特殊符合（如加号、等号）

### 语法分析/语义分析

#### 语法分析器

语法分析器（Grammar Parser）将对扫描器所产生的记号进行语法分析，从而产生语法树（Syntax Tree），也称抽象语法树（Abstract Syntax Tree，AST）。

常见的分析方式是自顶向下或者自底向上，以及采取[上下文无关语法](https://en.wikipedia.org/wiki/Context-free_grammar)（Context-free Grammer）作为分析手段。这块可参考一些计算机理论的资料，涉及的比较广。

但语法分析仅完成了对表达式的语法层面的分析，但并不清楚这个语句是否真正有意义，还需要一步语义分析。

#### 语义分析器

语义分析器（Semantic Analyzer）将会对对语法分析器所生成的语法树上的表达式标识具体的类型。主要分为两类：

- 静态语义：在编译器就可以确定的语义。

- 动态语义：在运行期才可以确定的语义。

在经过语义分析阶段后，整个语法树的表达式都会被标识上类型，如果有些类型需要进行隐式转换，语义分析程序将会在语法书中插入相应的转换点，成为有更具体含义的语义。

#### 实战演练

语法分析器生成的语法树，本质上就是以表达式（Expression）为节点的树。在 Go 语言中可通过 go/token、go/parser、go/ast 等相关方法生成语法树，代码如下：

```
func main() {
	src := []byte("package main\n\nimport (\n\t\"fmt\"\n)\n\nfunc main() {\n\tfmt.Println(\"Hello World.\")\n}")
	fset := token.NewFileSet() // positions are relative to fset
	f, err := parser.ParseFile(fset, "", src, 0)
	if err != nil {
		panic(err)
	}

	ast.Print(fset, f)
}
```

其经过语法分析器（自顶下向）分析后会所输出的结果如下：

```
     0  *ast.File {
     1  .  Package: 1:1
     2  .  Name: *ast.Ident {
     3  .  .  NamePos: 1:9
     4  .  .  Name: "main"
     5  .  }
     6  .  Decls: []ast.Decl (len = 2) {
     7  .  .  0: *ast.GenDecl {
     8  .  .  .  TokPos: 3:1
     9  .  .  .  Tok: import
    10  .  .  .  Lparen: 3:8
    11  .  .  .  Specs: []ast.Spec (len = 1) {
    12  .  .  .  .  0: *ast.ImportSpec {
    13  .  .  .  .  .  Path: *ast.BasicLit {
    14  .  .  .  .  .  .  ValuePos: 4:2
    15  .  .  .  .  .  .  Kind: STRING
    16  .  .  .  .  .  .  Value: "\"fmt\""
    17  .  .  .  .  .  }
    18  .  .  .  .  .  EndPos: -
    19  .  .  .  .  }
    20  .  .  .  }
    21  .  .  .  Rparen: 5:1
    22  .  .  }
    23  .  .  ...
    71  .  }
    72  .  Scope: *ast.Scope {
    73  .  .  Objects: map[string]*ast.Object (len = 1) {
    74  .  .  .  "main": *(obj @ 27)
    75  .  .  }
    76  .  }
    77  .  Imports: []*ast.ImportSpec (len = 1) {
    78  .  .  0: *(obj @ 12)
    79  .  }
    80  .  Unresolved: []*ast.Ident (len = 1) {
    81  .  .  0: *(obj @ 46)
    82  .  }
    83  }
```

- Package：解析出 package 关键字的位置，1:1 指的是位置在第一行的第一个。

- Name：解析出 package name 的名称，类型是 `*ast.Ident`，1:9 指的是位置在第一行的第九个。

- Decls：节点的顶层声明，其对应 BadDecl（Bad Declaration）、GenDecl（Generic Declaration）、FuncDecl（Function Declaration）。

- Scope：在此文件中的函数作用域，以及作用域对应的对象。

- Imports：在此文件中所导入的模块。

- Unresolved：在此文件中未解析的标识符。

- Comments：在此文件中的所有注释内容。

可视化后的语法树如下：

![image](https://image.eddycjy.com/552b1d6ea65da7470449eac084195f3f.jpg)

在上文中，主要涉及语法分析和语义分析部分，其归属于编译器前端，最终结果是得到了语法树，也就是常说是抽象语法树（AST）。有兴趣可以亲自试试 [yuroyoro/goast-viewer](http://goast.yuroyoro.net/)，会对语法树的理解更加的清晰。

### 中间语言生成

现代的编译器有这多个层次的优化，通常源代码级别会有一个优化过程。例如单纯的 1+2 的表达式就可以被优化。而在 Go 语言中，中间语言则会涉及[静态单赋值](https://en.wikipedia.org/wiki/Static_single_assignment_form)（Static Single Assignment，SSA）的特性。

假定有一个很简单的 SayHelloWorld 方法，如下：

```
package helloworld

func SayHelloWorld(a int) int {
    c := a + 2
    return c
}
```

想看到源代码到中间语言，再到 SSA 的话，可通过 `GOSSAFUNC` 编译源代码并查看：

```
$ GOSSAFUNC=SayHelloWorld go build helloworld.go
# command-line-arguments
dumped SSA to ./ssa.html
```

打开 ssa.html，可看到这个文件源代码所对应的语法树，好几个版本的中间代码以及最终所生成的 SSA。

![image](https://image.eddycjy.com/85cf8d94d2d3a4b1cbca13755feca46d.jpg)

从左往右依次为：Sources（源代码）、AST（抽象语法树），其次最右边第一栏起就是第一轮中间语言（代码），后面还有十几轮。

### 目标代码生成与优化

在中间语言生成完毕后，还不能直接使用。因为机器真正能执行的是机器码。这时候就到了编译器后端的工作了。在源代码级优化器产生中间代码时，则标志着接下来的过程都属于编译器后端。

编译器后端主要包括如下两类，作用如下：：

- 代码生成器（Code Generator）：代码生成器将中间代码转换成目标机器代码。

- 目标代码优化器（Target Code Optimizer）：针对代码生成器所转换出的目标机器代码进行优化。

在 Go 语言中，以上行为包含在前面所提到的十几轮 SSA 优化降级中，有兴趣可自行研究 SSA，最后在 genssa 中可看见最终的中间代码：

![image](https://image.eddycjy.com/191f907078d18683f6cae856d4b42fcb.jpg)

此时的代码已经降级的与最终的汇编代码比较接近，但还没经过正式的转换。

## 汇编

完成程序编译后，第三步将是 ”汇编“，汇编器会将汇编代码转变成机器可执行的指令，每一个汇编语句几乎都对应着一条机器指令。基本逻辑就是根据汇编指令和机器指令的对照表一一翻译。

在 Go 语言中，genssa 所生成的目标代码已经完成了优化降级，接下来会调用 `src/cmd/internal/obj` 包中的汇编器将 SSA 中间代码生成为机器码。我们可通过 `go tool compile -S` 的方式进行查看：

```
$ go tool compile -S helloworld.go 
"".SayHelloWorld STEXT nosplit size=15 args=0x10 locals=0x0
    0x0000 00000 (helloworld.go:3)  TEXT    "".SayHelloWorld(SB), NOSPLIT|ABIInternal, $0-16
    0x0000 00000 (helloworld.go:3)  FUNCDATA    $0, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
    0x0000 00000 (helloworld.go:3)  FUNCDATA    $1, gclocals·33cdeccccebe80329f1fdbee7f5874cb(SB)
    0x0000 00000 (helloworld.go:4)  MOVQ    "".a+8(SP), AX
    0x0005 00005 (helloworld.go:4)  ADDQ    $2, AX
    0x0009 00009 (helloworld.go:5)  MOVQ    AX, "".~r1+16(SP)
    0x000e 00014 (helloworld.go:5)  RET
    0x0000 48 8b 44 24 08 48 83 c0 02 48 89 44 24 10 c3     H.D$.H...H.D$..
go.cuinfo.packagename. SDWARFINFO dupok size=0
    0x0000 68 65 6c 6c 6f 77 6f 72 6c 64                    helloworld
gclocals·33cdeccccebe80329f1fdbee7f5874cb SRODATA dupok size=8
    0x0000 01 00 00 00 00 00 00 00                          ........
```

至此就完成了一个高级语言再到计算机所能理解的机器码转换的完整流程了。

## 总结

在本文中，我们基本了解了一个应用程序是怎么从源代码编译到最终的机器码，其中每一步展开都是一块非常大的计算机基础知识。若有读者对其感兴趣，可根据文中的实操步骤进行深入的剖析和了解。

在下一篇文章中，将会进一步针对最后的一个步骤链接来进行分析和了解其最后一公里。

================================================
FILE: content/posts/reading/programmer-linker.md
================================================
---
title: "链接器，应用编译的最后一公里路"
date: 2020-11-05T21:15:46+08:00
toc: true
draft: true
images:
tags: 
  - 程序员的自我修养
---

在《应用编译，计算机中那些一定要掌握的知识细节》中，我们完成了对 ”预处理、编译、汇编“ 三个基本步骤的了解。接下来剩余完整编译输出的最后一公里路，那就是 ”链接“。

编译器在经过扫描、语法分析、语义分析、源代码优化、代码生成和目标代码优化后，源代码终于被编译成了目标代码。但又遇到了新的问题，那就是 “目标代码中有变量定义在其他模块怎么办？”

而其他模块的全局变量和函数的绝对地址是在最终**链接阶段**才会确定，这是很重要的一步，有了模块串联才能让目标程序跑起来。

## 静态链接

### 地址分配

### 空间分配

### 符合决议

### 重定位

## 动态链接

## 总结

================================================
FILE: content/posts/reload-man.md
================================================
---
title: "为什么鼓励可以重塑一个职场人？"
date: 2021-12-31T12:54:56+08:00
toc: true
images:
tags: 
  - 职场成长
---

大家好，我是煎鱼。

最近在看书的时候看到了一句很经典的话：“**重塑一个人行为最好的方式是鼓励**”。平时我在多个领域的不同图书、不同面谈场合都能听到过不同的诠释。

![](https://files.mdnice.com/user/3610/9a4b75a6-b512-47b8-9c12-28d9b8e7a068.jpg)

可惜的是作者大多都没有指出是 “心理学” 的范畴，都只是表示应该要这么做，没有表示为什么，没有讲解来源，传播的信息非常的 3.5 手。

为此特意咨询了身边的一个心理学科班大佬，自打我认识她以来，每次开会都能看到她点头表示肯定，在我的记忆中非常深刻，非常有意思。

与她咨询过后，得出对应的是理论是 “**皮格马利翁效应**”。今天就进一步展开来简单学习、思考一下这为何物。

## 背景

皮格马利翁效应，又称毕马龙效应、罗森塔尔效应或期待效应，是指人（通常是指孩童或学生）在被赋予更高期望以后，他们会表现的更好的一种现象。

![图来自网络](https://files.mdnice.com/user/3610/e27b3d98-18c0-4cfc-bd4d-5900ac772351.png)

美国心理学家罗伯特·罗森塔尔和雷诺尔·雅各布森对此进行了研究。在他们的研究中发现，假设**老师对学生的期望加强，学生的表现也会相对加强**。

## 实验

在罗森塔尔的实验中，他们从 1~6 年级各选了 3 个班，对这 18 个班的学生进行了 “未来发展趋势测验”。并将一份 “最有发展前途者” 名单（实际上是随便抽取出来的）交给了校长和相关老师。

![图来自网络](https://files.mdnice.com/user/3610/6a09db03-5811-4ff7-b6b5-7a2cb2cc36e4.png)

在 8 个月后，罗森塔尔和助手们对那 18 个班级的学生进行复试，结果发现：**被期望的学生表现出更有适应能力、更有魅力、求知欲更强、智力更活跃等倾向**。

![图来自网络](https://files.mdnice.com/user/3610/c59f2415-812a-4d74-bc93-03f360944b79.png)

通过各种研究和试验得出结论：**认为教师的期望会传递给被期望的学生并产生鼓励效应，进而产生改变**。

也正是因为罗森塔尔对该效应在小学教学上予以验证提出，皮格马利翁效应也被称为“罗森塔尔效应”。

## 思考

回到最初的话题，为什么作者会说 ”重塑一个人行为最好的方式是鼓励”，这让我想起了非常著名两类思考模式：

![图来自网络](https://files.mdnice.com/user/3610/db4d42cc-9519-4c03-8961-57b3deaf9a65.png)

- 成长型思考模式：认为学习不在于天赋，在于努力，只要努力用功，什么都能学会。
- 固定型思考模式：特别相信天赋的作用，擅长的东西就是擅长，要是不擅长怎么学都没有用。

这其实就直接和 “鼓励” 有关系，我们接下来结合 “否定” 和 “鼓励” 来具体展开说说。

看看长期对一个人进行 “否定”，又或是进行 “鼓励” 可能会发生怎么样的事情，会不会改变一个人？

### 否定

如果在职场中，你**对一个人一直是否定、不认可，这对他是不好的**。你无论做什么，那个人总是挑刺，冷嘲热讽，在公开场合批判你。

可能会带来如下结果：
- 若他是一张白纸：极有可能就会认为自己不行，认为自己怎么学都没有用，无限的进行自我否定，很难走出来。
- 若他不是白纸：明确知道自己的底线，一直否定、不认可，也会反噬你团队，又或是对你有极大的意见。

这还是明确是否白纸的场景，但**更多的人不是非黑即白，也就是在灰色，处于两者之间**，不少人会怀疑人生。

逐渐才发现是**大家常说的职场 PUA**，这在勾心斗角的某些地方很常见。

### 鼓励

如果我们加之鼓励，多鼓励职场中的同事，在不同的人生阶段能带来不同的结果：
- 从小培养：埋下成长型思维模式的种子，他会主动把每一项任务都当成成长的机会，主动愿意花更长的时间钻研难题，主动选择更困难的任务。
- 成年发展：知道自己不应该被局限、固定的思维定式所控制，慢慢把 “固定型思考” 转变成 “成长型思考”，就会有较大的突破。

在职场中受到鼓励后，就**会朝着这块持续不断地突破，获得自我和周遭的成就和认同感，进而更进一步的拓展，得到更多的发展空间**，这就是 “鼓励” 的力量。

## 职场和工作

无论是哪种形式：爱鼓励、爱批评、爱否定。这世界上都大有人在，总是包罗万象，走 “二极管” 是错误的，单一的某种方式总是会带来极端。
- 若是永远只有 “鼓励”：那社会上人是千人千面的，习惯性被鼓励，没人鼓励，就动不了了。
- 若是只有 “批判”、“否定”：那就更糟糕了。一个只会骂人的 Leader，你愿意跟吗？我相信肯定不愿意。

在职场中，除了要多鼓励他人、接受他人鼓励外，我们要多和公司内、同行、同业圈的小伙伴聊聊，及时找到自己的模糊、问题、错误的点。

再针对性释出自己的解决方案，和朋友共同探索，寻找新的解决思路或方法，持续优化下去。

这样就能够有一定的突破和增长，想永远都是问题，想后做了，才是答案，才能改进。

## 最后

如果是你，孩子考试考得不错，作业写得好，如何表扬孩子聪明？
- A：“这题你都会做？我儿子太聪明了！”
- B：“不错啊！这次做的很好，看来你下了很大功夫！下次继续！只要你努力！什么事都能做成！”

选择 A，还是 B 呢？

**欢迎大家在评论区留言和交流，说出你的答案和我们在思考**！


================================================
FILE: content/posts/where-is-proto.md
================================================
---
title: "Proto 代码到底放哪里？"
date: 2020-05-23T15:07:37+08:00
draft: false
toc: true
images:
tags: 
  - protobuf
---

虽然公司已经从大单体切换为微服务化有一定的年头了，但一些细节方面的处理总会有不同的人有不同的看法，这其中一个讨论点，就是 Proto 这个 IDL 的代码到底放在哪里？

目前来看，一共有如下方案， 我们一起来探讨一下 Proto 的存储方式和对应带来的优缺点。

## 方案一：存放在代码仓库

直接将项目所依赖到的所有 Proto 文件都存放在 `proto/` 目录下，不经过开发工具的自动拉取和发布：

![image](https://image.eddycjy.com/7e95a76d548197cf73e7238ee5df27e6.jpg)

### 缺点

1. 项目所有依赖的 Proto 都存储在代码仓库下，因此所有依赖 Proto 都需要人工的向其它业务组 “要” 来，再放到 `proto/` 目录下，人工介入极度麻烦。

2. Proto 升级和变更，经常要重复第一步，沟通成本高。

### 优点

1. 项目所有依赖的 Proto 都存储在代码仓库下，因此不涉及个人开仓库权限的问题。

2. 多 Proto 的切换开销减少，因为都在代码仓库下，不需要看这看那。

## 方案二：独立仓库

独立仓库存储是我们最早采取的方式，也就是每个服务对应配套一个 Proto 仓库：

![image](https://image.eddycjy.com/a7575628ff1ae9179f022d477aba9df1.png)

这个方案的好处就是可以独立管理所有 Proto 仓库，并且权限划分清晰。但最大的优点也是最大的缺点，因为一个服务会依赖多个 Proto 仓库，并且存在跨业务组调用的情况：

![image](https://image.eddycjy.com/31c5a5b5652f44750124c15e1c0ef397.jpg)

如上图所示，svc-user 服务分别依赖了三块 Proto 仓库，分别是自己组的、业务组 A、业务组 B 总共的 6 个 Proto 仓库。

### 缺点

1. 假设你是一个新入职的开发人员，那么你就需要找不同的业务组申请不同的仓库权限，非常麻烦。如果没有批量赋权工具，也没有管理者权限，那么就需要一个个赋权，非常麻烦。
2. 在运行服务的时候，你需要将所有相关联的 Proto 仓库拉取下来，如果没有工具做半自动化的支持，麻烦程度无法忍受。

### 优点

1. 使得安全性较高（但 IDL 本身没有太多的秘密）。

2. 按需拉取，不需要关注其余的服务 Proto。

## 方案三：集中仓库

集中仓库也是一些公司考虑的方式之一，是按公司或大事业部的维度进行 Proto 代码的存储，这样子只需要拉取一个仓库，就可以获取到所有所需的 IDL：

![image](https://image.eddycjy.com/9f0c7821aa2d42857685e04d9df25740.jpg)

### 缺点

1. 安全性下降，因为其它业务组的 IDL 也全都 “泄露” 了。

2. 非按需拉取，在查看原始文件时，需要关注一些多余的。

### 优点

1. 只需要拉取一次 Proto 仓库就可以轻松把一个服务所需的 IDL 集齐。

2. 仓库权限管理的复杂度下降。

## 方案四：镜像仓库

结合上面几种方案的特点，我们也可以得出镜像仓库的方式，也就是自己服务的 Proto 文件存放在代码仓库的 proto 文件中，在本次 feature 提交或发布后，自动同步到镜像仓库去。

而你所依赖的其他服务 Proto 则直接通过读取集中的镜像仓库的方式获取：

![image](https://image.eddycjy.com/d90a0040923aacced41549ea902e6cde.jpg)

这样子的话，通过开发工具的配合，开发人员在开发时就只需要关注自己项目的 Proto，集中的镜像仓库用于构建和部署时就可以了，大幅度降低了多 Proto 的关注和切换开销。

## 方案五：其他

本质上上述的所有方案多多少少都有一些利弊存在，并且都需要开发工具来进行支持，否则实操起来还是非常麻烦。

如果想一劳永逸，可以通过云开发环境来解决，因为在分配云开发机时，你已经有了身份认证，你能够拥有什么权限，不能拥有什么权限，基本都是明确的，并且一般在组内、跨组联调时，也可以直接调度，不需要像其它方案那样进行过多的关注，甚至在自己本地运行一套微服务。

但这需要大量的工具/资源支持。

## 小结

在本文中我介绍了比较常见的 5 种 Proto 代码的管理方式，其各有利弊，不同公司不同人的理解或适配度都不一样，大家可以根据实际环境进行选用，并且建议拉上核心的人员进行讨论和选型，因为 Proto 代码涉略面还是比较广的，多多少少都有人有不一样的看法。

================================================
FILE: content/posts/why-container-memory-exceed.md
================================================
---
title: "为什么容器内存占用居高不下，频频 OOM"
date: 2020-06-07T14:52:19+08:00
toc: true
tags: 
  - go
---


最近我在回顾思考（写 PPT），整理了现状，发现了这个问题存在多时，经过一番波折，最终确定了元凶和相对可行的解决方案，因此也在这里分享一下排查历程。

时间线：

- 在上 Kubernetes 的前半年，只是用 Kubernetes，开发没有权限，业务服务极少，忙着写新业务，风平浪静。

- 在上 Kubernetes 的后半年，业务服务较少，偶尔会阶段性被运维唤醒，问之 “**为什么你们的服务内存占用这么高，赶紧查**”。此时大家还在为新业务冲刺，猜测也许是业务代码问题，但没有调整代码去尝试解决。

- 在上 Kubernetes 的第二年，业务服务逐渐增多，普遍增加了容器限额 Limits，出现了好几个业务服务是内存小怪兽，因此如果不限制的话，服务过度占用会导致驱逐，因此反馈语也就变成了：“**为什么你们的服务内存占用这么高，老被 OOM Kill，赶紧查**”。据闻也有几个业务大佬有去排查（因为 OOM 反馈），似乎没得出最终解决方案。

不禁让我们思考，为什么个别 Go 业务服务，Memory 总是提示这么高，经常达到容器限额，以至于被动 OOM Kill，是不是有什么安全隐患？

## 现象

### 内存居高不下

发现个别业务服务内存占用挺高，触发告警，且通过 Grafana 发现在凌晨（没有什么流量）的情况下，内存占用量依然拉平，没有打算下降的样子，高峰更是不得了，像是个内存炸弹：

![image](https://image.eddycjy.com/2e6c8c153836b29175dff7623ec67a0a.png)

并且我所观测的这个服务，早年还只是 100MB。现在随着业务迭代和上升，目前已经稳步 4GB，容器限额 Limits 纷纷给它开道，但我想总不能是无休止的增加资源吧，这是一个大问题。

### 进入重启怪圈

有的业务服务，业务量小，自然也就没有调整容器限额，因此得不到内存资源，又超过额度，就会进入疯狂的重启怪圈：

![image](https://image.eddycjy.com/95644633a2d55cb2f2684a23d3f3f189.png)

重启将近 300 次，非常不正常了，更不用提所接受到的告警通知。

## 排查

### 猜想一：频繁申请重复对象

出现问题的个别业务服务都有几个特点，那就是基本为图片处理类的功能，例如：图片解压缩、批量生成二维码、PDF 生成等，因此就怀疑是否在量大时频繁申请重复对象，而 Go 本身又没有及时释放内存，因此导致持续占用。

#### sync.Pool

基本上想解决 “频繁申请重复对象”，我们大多会采用多级内存池的方式，也可以用最常见的 sync.Pool，这里可参考全成所借述的《Go 夜读》上关于 sync.Pool 的分享，关于这类情况的场景：

> 当多个 goroutine 都需要创建同⼀个对象的时候，如果 goroutine 数过多，导致对象的创建数⽬剧增，进⽽导致 GC 压⼒增大。形成 “并发⼤－占⽤内存⼤－GC 缓慢－处理并发能⼒降低－并发更⼤”这样的恶性循环。

#### 验证场景

在描述中关注到几个关键字，分别是并发大，Goroutine 数过多，GC 压力增大，GC 缓慢。也就是需要满足上述几个硬性条件，才可以认为是符合猜想的。

通过拉取 PProf goroutine，可得知 Goroutine 数并不高：

![image](https://image.eddycjy.com/4adaadade78389230318c41d006de4ef.png)

另外在凌晨长达 6 小时，没有什么流量的情况下，也不符合并发大，Goroutine 数过多的情况，若要更进一步确认，可通过 Grafana 落实其量的高低。

从结论上来讲，我认为与其没有特别直接的关系，但猜想其所对应的业务功能到导致的间接关系应当存在。

### 猜想二：不知名内存泄露

内存居高不下，其中一个反应就是猜测是否存在泄露，而我们的容器中目前只跑着一个 Go 进程，因此首要看看该 Go 应用是否有问题。这时候可以借助 PProf heap（可以使用 base -diff）：

![image](https://image.eddycjy.com/877545ab97b21e68b580567ccf38e08b.png)

显然其提示的内存使用不高，那会不会是 PProf 出现了 BUG 呢。接下通过命令也可确定 Go 进程的 RSS 并不高，但 VSZ 却相对 “高” 的惊人，我在 19 年针对此写过一篇[《Go 应用内存占用太多，让排查？（VSZ篇）》](https://eddycjy.com/posts/go/talk/2019-09-24-why-vsz-large) ，这次 VSZ 过高也给我留下了一个念想。

从结论上来讲，也不像 Go 进程内存泄露的问题，因此也将其排除。

### 猜想三：madvise 策略变更

- 在 Go1.12 以前，Go Runtime 在 Linux 上使用的是 `MADV_DONTNEED` 策略，可以让 RSS 下降的比较快，就是效率差点。

- 在 Go1.12 及以后，Go Runtime 专门针对其进行了优化，使用了更为高效的 `MADV_FREE` 策略。但这样子所带来的副作用就是 RSS 不会立刻下降，要等到系统有内存压力了才会释放占用，RSS 才会下降。

查看容器的 Linux 内核版本：

```
$ uname -a
Linux xxx-xxx-99bd5776f-k9t8z 3.10.0-693.2.2.el7.x86_64 
```

但 `MADV_FREE` 的策略改变，需要 Linux 内核在 4.5 及以上（详细可见 [go/issues/23687](https://github.com/golang/go/issues/23687)），显然不符合，因此也将其从猜测中排除。

### 猜想四：监控/判别条件有问题

会不会是 Grafana 的图表错了，Kubernetes OOM Kill 的判别标准也错了呢，显然不大可能，毕竟我们拥抱云，阿里云 Kubernetes 也运行了好几年。

![image](https://image.eddycjy.com/ad7ca63b33af2b856a8efcf7ab36dbd4.jpg)

但在这次怀疑中，我了解到 OOM 的判断标准是 container_memory_working_set_bytes 指标，因此有了下一步猜想。

### 猜想五：容器环境的机制

既然不是业务代码影响，也不是 Go Runtime 的直接影响，那是否与环境本身有关呢，我们可以得知容器 OOM 的判别标准是 container_memory_working_set_bytes（当前工作集）。

而 container_memory_working_set_bytes  是由 cadvisor 提供的，对应下述指标：

![image](https://image.eddycjy.com/288361fd15c915e6ff1bb6d21f943939.jpg)

从结论上来讲，Memory 换算过来是 4GB+，石锤。接下来的问题就是 Memory 是怎么计算出来的呢，显然和 RSS 不对标。

## 原因

从 [cadvisor/issues/638](https://github.com/google/cadvisor/issues/638) 可得知 container_memory_working_set_bytes 指标的组成实际上是 RSS + Cache。而 Cache 高的情况，常见于进程有大量文件 IO，占用 Cache 可能就会比较高，猜测也与 Go 版本、Linux 内核版本的 Cache 释放、回收方式有较大关系。

![image](https://image.eddycjy.com/36d4ccc1cf705be334d53766f4ea8dc2.jpg)

而各业务模块常见功能，如：

- 批量图片解压缩。
- 批量二维码生成。 
- 批量上传渲染后图片。
- 批量 PDF 生成。
- ...

只要是涉及有大量文件 IO 的服务，基本上是这个问题的老常客了，写这类服务基本写一个中一个，因为这是一个混合问题，像其它单纯操作为主的业务服务就很 “正常”，不会出现内存居高不下。

## 解决方案

在本场景中 cadvisor 所提供的判别标准 container_memory_working_set_bytes 是不可变更的，也就是无法把判别标准改为 RSS，因此我们只能考虑掌握主动权。

### 开发角度

使用类 sync.Pool 做多级内存池管理，防止申请到 “不合适”的内存空间，常见的例子： ioutil.ReadAll：

```
func (b *Buffer) ReadFrom(r io.Reader) (n int64, err error) {
    …
    for {
        if free := cap(b.buf) - len(b.buf); free < MinRead {
            newBuf := b.buf
            if b.off+free < MinRead {
                    newBuf = makeSlice(2*cap(b.buf) + MinRead)  // 扩充双倍空间
                    copy(newBuf, b.buf[b.off:])
            }
        }
    }
}

```

核心是做好做多级内存池管理，因为使用多级内存池，就会预先定义多个 Pool，比如大小 100，200，300的 Pool 池，当你要 150 的时候，分配200，就可以避免部分的内存碎片和内存碎块。

但从另外一个角度来看这存在着一定的难度，因为你怎么知道什么时候在哪个集群上会突然出现这类型的服务，何况开发人员的预期情况参差不齐，写多级内存池写出 BUG 也是有可能的。

让业务服务无限重启，也是不现实的，**被动重启，没有控制，且告警，存在风险**。

### 运维角度

为了掌握主动权，我们可以在部署环境可以配合脚本做 “手动” HPA，当容器内存指标超过约定限制后，起一个新的容器替换，再将原先的容器给释放掉，就可以在预期内替换且业务稳定了。

![image](https://image.eddycjy.com/2b449204373cd0d7c8e8501a326061a7.jpg)

## 总结

根据上述排查和分析结果，原因如下：

- 应用程序行为：文件处理型服务，导致 Cache 占用高。
- Linux 内核版本：版本比较低（BUG?），不同 Cache 回收机制。
- 内存分配机制：在达到 cgroup limits 前会尝试释放，但可能内存碎片化，也可能是一次性索要太多，无法分配到足够的连续内存，最终导致 cgroup oom。

![image](https://image.eddycjy.com/391085a138e86866b78c960e4de516c7.jpg)

从根本上来讲，应用程序需要去优化其内存使用和分配策略，又或是将其抽离为独立的特殊服务去处理。并不能以目前这样简单未经多级内存池控制的方式去使用，否则会导致内存使用量越来越大。

而从服务提供的角度来讲，我们并不知道这类服务会在什么地方出现又何时会成长起来，因此我们需要主动去控制容器的 OOM，让其实现优雅退出，保证业务稳定和可控。

因此如果可以，升级 Linux 内核版本走 cgroup v2 极有可能可以解决问题。

## 回顾

虽然这问题时间跨度比较长，整体来讲都是阶段性排查，本质上可以说是对 Kubernetes 的不熟悉有关。但综合来讲这个问题涉及范围比较大，因为内存居高不下的可能性有很多种，要一个个排查，开发权限有限，费时费力。

基本排查思路就是：

1. 怀疑业务代码（PProf）。
2. 怀疑其它代码（PProf）。
3. 怀疑 Go Runtime 。
4. 怀疑工具。
5. 怀疑环境。

非常感谢在这大段时间内被我咨询的各位大佬们，感觉就是隔了一层纱，捅穿了就很快就定位到了，大家如果有其它解决方案也欢迎随时沟通。


================================================
FILE: content/posts/why-container-memory-exceed2.md
================================================
---
title: "为什么容器内存占用居高不下，频频 OOM（续）"
date: 2020-06-19T21:29:08+08:00
toc: true
tags: 
  - go
---

在上周的文章[《为什么容器内存占用居高不下，频频 OOM》](/posts/why-container-memory-exceed/) 中，我根据现状进行了分析和说明，收到了很多读者的建议和疑惑，因此有了这一篇文章，包含更进一步的说明和排查。

## 疑问

一般系统内存过高的情况下，可以通过 `free -m` 查看当前系统的内存使用情况：

![image](https://image.eddycjy.com/daf2a1d53f4bf0f21e315d2333e08159.png)

在发现是系统内存占用高后，就会有读者会提到，为什么不 “手动清理 Cache”，因为 Cache 高的话，可以通过 drop_caches 的方式来清理：

1. 清理 page cache：

```
$ echo 1 > /proc/sys/vm/drop_caches
```

2. 清理 dentries 和 inodes：

```
$ echo 2 > /proc/sys/vm/drop_caches
```

3. 清理 page cache、dentries 和 inodes：

```shell
$ echo 3 > /proc/sys/vm/drop_caches
```

但新问题又出现了，因为我们的命题是在容器中，在 Kubernetes 中，若执行 drop_caches 相关命令，将会对 Node 节点上的所有其他应用程序产生影响，尤其是那些占用大量 IO 并由于缓冲区高速缓存而获得更好性能的应用程序，可能会产生 “负面” 后果。

我想这并不是一个好办法。

## 表象

回归原始，那就是为什么要排查这个问题，本质原因就是容器设置了 Memory Limits，而容器在运行中达到了 Limits 上限，被 OOM 掉了，所以我们想知道为什么会出现这个情况。

在前文中我们针对了五大类情况进行了猜想：

- 频繁申请重复对象。
- 不知名内存泄露。
- madvise 策略变更。
- 监控/判别条件有问题。
- 容器环境的机制。

在逐一排除后，后续发现容器的 Memory OOM 判定标准是 container_memory_working_set_bytes 指标，其实际组成为 RSS + Cache（最近访问的内存、脏内存和内核内存）。

在排除进程内存泄露的情况下，我们肯定是希望知道 Cache 中有什么，为什么占用了那么大的空间，此时我们可以通过 Linux pmap 来查看该容器进程的内存映射情况：

![image](https://image.eddycjy.com/0bb82eabe1fcc1a5a65f4382932a6d2c.jpg)

在上图中，我们发现了大量的 mapping 为 anon 的内存映射，最终 totals 确实达到了容器 Memory 相当的量，那么 anon 又是什么呢。实质上 anon 行表示在磁盘上没有对应的文件，也就是没有实际存在的载体，是 anonymous。

## 思考

既然存在如此多的 anon，结合先前的考虑，我们知道出现这种情况的服务都是文件处理型服务，包含大量的批量生成图片、生成 PDF 等资源消耗型的任务，也就是会瞬间申请大量的内存，使得系统的空闲内存触及全局最低水位线（global wmark_min），而在触及全局最低水位线后，会尝试进行回收，实在不行才会触发 cgroup OOM 的行为。

那么更进一步思考的是两个问题，一个是 cgroup 达到 Limits 前的尝试释放仍然不足以支撑所需申请的连续内存段，而另外一个问题就是为什么 Cache 并没有释放：

![image](https://image.eddycjy.com/2e6c8c153836b29175dff7623ec67a0a.png)

通过上图，可以肯定该服务在凌晨 00：00-06：00 是没有什么流量的，但是 container_memory_working_set_bytes 指标依旧稳定不变，排除 RSS 的原因，那配合指标的查看基本确定是该 cgroup 的 Cache 没有释放。

而 Cache 的占用高，主要考虑是由于其频繁操作文件导致，因为在 Linux 中，在第一次读取文件时会将一份放到系统 Cache，另外一份则放入进程内存中使用。关键点在于当进程运行完毕关闭后，系统 Cache 是不会马上回收的，需要经过系统的内存管理后再适时释放。

但我们发现 Cache 的持续不释放，进程也没外部流量，RSS 也低的可怜，Cache 不像被进程占用住了的样子（这一步的排除很重要），最终就考虑到是否 Linux 内核在这块内存管理上存在 BUG 呢？

## 根因

### 问题版本

该服务所使用的 Kubernetes 是 1.11.5 版本，Linux 内核版本为 3.10.x，时间为 2017 年 9 月：

```
$ uname -a
Linux xxxxx-xxx-99bd5776f-k9t8z 3.10.0-693.2.2.el7.x86_64 #1 SMP Tue Sep 12 22:26:13 UTC 2017 x86_64 Linux
```

都算是有一定年代的老版本了。

### 原因分析

memcg 是 Linux 内核中管理 cgroup 内存的模块，但实际上在 Linux 3.10.x 的低内核版本中存在不少实现上的 BUG，其中最具代表性的是 memory cgroup 中 kmem accounting 相关的问题（在低版本中属于 alpha 特性）：

- slab 泄露：具体可详见该文章 [SLUB: Unable to allocate memory on node -1](https://pingcap.com/blog/try-to-fix-two-linux-kernel-bugs-while-testing-tidb-operator-in-k8s/#bug-1-unstable-kmem-accounting) 中的介绍和说明。

- memory cgroup 泄露：在删除容器后没有回收完全，而 Linux 内核对 memory cgroup 的总数限制是 65535 个，若频繁创建删除开启了 kmem 的 cgroup，就会导致无法再创建新的 memory cgroup。

当然，为什么出现问题后绝大多数是由 Kubernetes、Docker 的相关使用者发现的呢（从 issues 时间上来看），这与云原生的兴起，这类问题与内部容器化的机制相互影响，最终开发者 “发现” 了这类应用频繁出现 OOM，于是开始进行排查。

## 解决方案

### 调整内核参数

关闭 kmem accounting：

```
cgroup.memory=nokmem
```

也可以通过 kubelet 的 nokmem Build Tags 来编译解决：

```
$ kubelet GOFLAGS="-tags=nokmem"
```

但需要注意，kubelet 版本需要在 v1.14 及以上。

### 升级内核版本

升级 Linux 内核至 kernel-3.10.0-1075.el7 及以上就可以修复这个问题，详细可见 [slab leak causing a crash when using kmem control group](https://bugzilla.redhat.com/show_bug.cgi?id=1507149#c101)，其在发行版中 CentOS 7.8 已经发布。

## 总结

经过内部讨论，由于种种原因（例如：Linux、Kubernetes 太低），我们选择了升级 Linux 版本，也就是 CentOS 8，这样子其内核版本就会到达至 4.x（cgroup 已经健壮了许多，且在 4.5 cgroup v2 已经 GA），相关问题已经修复，并同步设置 `cgroup.memory=nokmem` 即可解决/避免相关问题。

而在写下这篇文章时，我们可以看到 kmem accounting 的不少问题都已经被修复或提上日程，这对本次排查提供了相当大的便利，在确定问题的所在后根据 cgroup leak 沿着排查下去，基本都能看到大量的前人所经历过的 “挣扎”，大家若有兴趣，也可以跟着参考所提供的的链接做更一进步的深入了解。

但事实上，不管哪个 Linux 内核版本，都存在着或多或少的问题，需要做好适当的心理准备，否则就会遇到 “没上容器时好好的” 的窘境，查起问题更麻烦。

## 后话

现在生产集群已经迁移完毕多日，通过近期的观察，已经确定了这个问题的修复和解决。这是原本的情况：

![image](https://image.eddycjy.com/2e6c8c153836b29175dff7623ec67a0a.png)

新生产集群，经过数日后：

![image](https://image.eddycjy.com/c6ae131d437aae460e6fe70c9cf076b7.png)

通过对比，可以明确的看到，在原本的趋势图中，其在达到当时的内存高位后，即使在凌晨没有流量的情况下，容器内存也依然居高不下，纹丝不动，不会下降。

再反观最新的趋势图，在没有流量打入的情况下，容器内存开始下降，说明 Cahce 的自动回收已经正常的在运行了。

而自动回收的标准，一般常见于接近或达到全局内存水位的情况，系统会尽最大可能进行 Cache 的回收，以确保系统的正常运行：

![image](https://image.eddycjy.com/800df66be75520f982e650b6303bf9e8.jpg)

至此，也就达到了修复这个问题的目的，解决了这一个长达两年的迷之内存漩涡。

## 参考

- [show_bug.cgi?id=1507149#c101](https://bugzilla.redhat.com/show_bug.cgi?id=1507149#c101)
- [unstable-kmem-accounting](https://pingcap.com/blog/try-to-fix-two-linux-kernel-bugs-while-testing-tidb-operator-in-k8s/#bug-1-unstable-kmem-accounting)
- [kmem accounting 导致的 cgroup 泄漏问题](https://blog.witd.in/2019/12/09/kmem-accounting%E5%AF%BC%E8%87%B4%E7%9A%84cgroup%E6%B3%84%E6%BC%8F%E9%97%AE%E9%A2%98/)
- [crash due to k8s 1.9.x](https://github.com/kubernetes/kubernetes/issues/61937)
- [记一次k8s cgroup内存泄露问题修复](http://www.iceyao.com.cn/2020/01/04/%E8%AE%B0%E4%B8%80%E6%AC%A1k8s-cgroup%E5%86%85%E5%AD%98%E6%B3%84%E9%9C%B2%E9%97%AE%E9%A2%98%E8%A7%A3%E5%86%B3/)
- [Cgroup 泄漏--潜藏在你的集群中](https://tencentcloudcontainerteam.github.io/2018/12/29/cgroup-leaking/)


================================================
FILE: content/posts/why-mq.md
================================================
---
title: "《漫谈 MQ》要消息队列（MQ）有什么用？"
date: 2021-12-31T12:54:50+08:00
toc: true
images:
tags: 
  - mq
---

大家好，我是煎鱼。想是问题，做是答案。

最近我有一个朋友公司踩了不少消息队列（MQ）的坑，让人无奈不已。因此计划写 MQ 系列的技术文章，来科普更多这块的知识。

目前 MQ 也是互联网应用中非常常用的基础组件了，面试特爱问。基本有一定规模的系统都能看见他的踪影。

无论是 RocketMQ、Kafka、RabbitMQ 等，都围绕着根本的设计出发产生不同的高级功能，甚至可能是雷同的设计有 N 个名字。

## 什么是 MQ

MQ 一般代指消息队列（Message Queue）。它是一个抽象层，允许多个进程（可能在不同的机器上）通过各种模式（例如：点对点，发布订阅等）进行通信。

也可以根据不同的实现，它可以被配置为保证可靠性、错误报告、安全、发现、性能等。

## 为什么需要 MQ

在当下 MQ 的必要场景，比较经典的说辞就是 “异步、削峰、解耦”。是各类秒杀系统的设计核心，甚至会作为不少云厂商的卖点，每家都有自己的生态圈。

核心分为三个要点：
- 解耦。
- 削峰。
- 异步。

### 解耦

在业务系统设计中，我们常常会与一个平台系统 A，他汇聚了许许多多的系统的对接。例如，系统 A 作为平台拥有大量用户操作，自然就有非常多的用户行为。

虽然他自己可能不大需要，但是其他子系统就不同了，会要系统 A 来调用他们提供的接口，传输各种行为数据。

其链路依赖如下图：

![多重依赖](https://image.eddycjy.com/84478d2799861f81519ede0ba4ceb91d.jpg)

这时候作为平台方的系统 A 就烦死了，来一个要对接一个，就得安排一个人排工期和迭代。对方还有可能出现系统不稳定，还得关注他们的稳定性和诉求。

但用了 MQ 后就不一样了，如下图：

![MQ 解耦直接依赖](https://image.eddycjy.com/b6c79dbe5c848ed32e347de4042cd9b6.jpg)

系统 A 只需要将消息放到 MQ 中去，不管以后是对接系统 B、C、D、E...，他都不需要太关心，不用一个个对接。用业务同学的话来讲，就是：“自己看文档，去 MQ 里拿，别来骚扰我”。

以此 MQ 达到了系统间解耦的目的。

### 削峰

在 2C 类别的业务系统中，常常会有活动的概念，要面向用户做促销，像我们常见的双 11、618 都是这类营销，也是营销场景。

但这种场景之下，会对系统产生较大的冲击。类似八二原则，也就是 80% 的流量集中在某个时间冲击进来，形成了流量尖峰（高 QPS），系统会因为承受不了如此大的压力，从而宕机。

如下图：

![用户直接并发访问](https://image.eddycjy.com/e396606bb1aec70b43a7016933880f09.jpg)

用户的请求会经由系统 A 直击数据库。当然，在活动场景下的大流量，数据库自然也就撑不住了。

我们可以利用 MQ 做削峰，系统 A 直接把消息写入 MQ，再让系统 B、C、D 自己主动地根据自身情况来 MQ 拉取消息，又或是接受消息的推送：

![利用 MQ 削峰](https://image.eddycjy.com/126ec27324c95ce6311078a8e8849d54.jpg)

这样一来，MQ 作为一个 “转发器”，流量不会直接打到底层，也保证了各业务系统可根据自己的实际负载来决定消费消息的速度，起到流量削峰放缓的作用。

### 异步

在没有引入 MQ 组件的时候，我们系统 A 因业务需求要调好几个接口时，都可能需要专门的写个异步操作，否则就会导致阻塞等待响应过久。

但是使用 MQ 后，系统只需要快速地将消息写入 MQ 中，接着就可以返回了：

![MQ 异步操作](https://image.eddycjy.com/40efbfcc5453aff5b58e85d11fb3d291.jpg)

也就是真正的业务操作，被异步化了。“内部” 的区域是业务系统自身需要关注的，而经由 MQ 的 “外部” 操作与系统 A 无关，自然异步处理也问题不大。

## MQ 三要素

MQ 一共有三个基本角色，分别是：
- 生产者（Producer）：负责生产消息。
- 消费者（Consumer）：负责消费消息。
- 队列（Queue）：负责存储消息。

这么一看，MQ 就是一个很基础的东西，基本就是一发一存一消费的模型：

![MQ 三要素](https://image.eddycjy.com/60a3665e5c14ec8b18a0ec14c31b91b4.jpg)

1. 在 MQ 中传来传去的内容：就是 “消息”，消息是我们业务要传输的数据内容。内容格式为自定义，只要两边商议清楚能解析出来即可。比较常见是像是：JSON、Protobuf 等。

2. 消息在 MQ 的队列组件：承载着传输消息的作用，队列是先进先出的数据结构，生产者的消息入队就是发消息，消费者消费消息，也就是队列出队。

## 消息模型

随着消息的不断规模使用和应用，目前业内常见的有两种模型：
- 点对点模型。
- 发布/订阅模型。

### 点对点模型

点对点是 MQ 最初的结构，也就是 “生产者-队列-消费者” 的模型：

![点对点模型](https://image.eddycjy.com/597c3a216c23124f0a0c855b5777a85d.jpg)

生产者将消息写入队列，消费者再从队列中读取出消息出来，完成一个标准动作。

当然，在真实环境中，是允许有多个生产者和多个消费者的，也可以根据不同的业务诉求做队列的隔离。

### 发布/订阅模型

发布/订阅是 MQ 逐渐延伸出来的诉求，因为在实际业务场景中，我们需要将一份消息分发给多个消费者。

多个消费者都要针对这份数据做一些自己的业务处理，那么点对点的就不合适了，除非点对点的开通 N 个队列，但消息的体量可也不少，也不高效，这显然很浪费。

从业务场景来讲，就像平时系统 A 有一份用户行为数据，下游有 N 个系统需要，那咋办。最适合的就是 “发布者-Topic-订阅者” 的模型：

![发布/订阅模型](https://image.eddycjy.com/a64d93b952cb9953af355cf2e56ee1a4.jpg)

在该模型中，“生产者” 变成 “发布者”，“消费者” 变成了 “订阅者”，以往的 “队列” 也改变了他单一的属性，拆成了更多的组件。一般就是 “主题” 了，也就是 Topic 来做消息存储等。

订阅者只需要订阅 Topic，就可以收到发布者每次发布的这个 Topic 的全量消息，以此达到诉求。

## 总结

在今天这篇文章中，我们介绍了消息队列（MQ）的相关核心内容：
- MQ 基本介绍和说明。
- MQ 常见的三要素和三大特性进行了分析说明
- MQ 常见的 “点对点” 和 “发布/订阅” 模型。

MQ 总是有利有弊的，在初步了解后，接下来的文章我们将会持续剖析，欢迎关注煎鱼，继续学习 ：）

## 参考
- [What is an MQ and why do I want to use it?](https://stackoverflow.com/questions/2868800/what-is-an-mq-and-why-do-i-want-to-use-it)
- [消息队列（mq）是什么？](https://www.zhihu.com/question/54152397)
- [MQ 消息队列的解耦、接口异步处理、削峰](https://blog.csdn.net/maihilton/article/details/81628152)

================================================
FILE: content/prometheus-categories.md
================================================
---
title: "《跟煎鱼学 Prometheus》"
date: "2020-05-16"
---

请注意，这不是成品，随时可能会对以前的章节进行修改。那么为什么要放出来呢，当然是为了催更自己。

1. [Prometheus 快速入门](/posts/prometheus/2020-05-16-startup)
2. [Prometheus 四大度量指标的了解和应用](/posts/prometheus/2020-05-16-metrics)
3. [使用 Prometheus 对 Go 程序进行指标采集](/posts/prometheus/2020-05-16-pull)

### 我的公众号

平时喜欢分享 Go 语言、微服务架构和奇怪的系统设计，欢迎关注我的公众号：

![image](https://image.eddycjy.com/7074be90379a121746146bc4229819f8.jpg)

================================================
FILE: layouts/_default/baseof.html
================================================
<!DOCTYPE html>
<html lang="{{.Site.LanguageCode}}">

<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta http-equiv="X-UA-Compatible" content="ie=edge">
	{{- with .Site.Params.themeColor }}
	<meta name="theme-color" content="{{.}}">
	<meta name="msapplication-TileColor" content="{{.}}">
	{{- end }}
	{{- partial "structured-data.html" . }}
	{{- partial "favicons.html" }}
	<title>{{.Title}}</title>
	{{ range .AlternativeOutputFormats -}}
		{{ printf `<link rel="%s" type="%s+%s" href="%s" title="%s" />` .Rel .MediaType.Type .MediaType.Suffix .Permalink $.Site.Title | safeHTML }}
	{{ end -}}
	{{ $style := resources.Get "scss/style.scss" | resources.ExecuteAsTemplate "css/style.css" . | toCSS | minify | fingerprint -}}
	<link rel="stylesheet" href="{{ $style.Permalink }}">
	{{- block "head" . -}}{{- end }}
	{{- range .Site.Params.customCSS }}
	<link rel="stylesheet" href="{{ . | absURL }}">
	{{- end }}
	{{- if templates.Exists "partials/extra-head.html" -}}
	{{ partial "extra-head.html" . }}
	{{- end }}
</head>

<body id="page">
	{{ block "header" . -}}{{ end -}}
	{{ block "main" . -}}{{ end -}}
	{{ block "footer" . -}}{{ end }}
	{{ $script := resources.Get "js/main.js" | minify | fingerprint -}}
	<script src="{{ $script.Permalink }}"></script>
	{{- partial "analytics.html" . }}
	{{- if templates.Exists "partials/extra-foot.html" -}}
	{{ partial "extra-foot.html" . }}
	{{- end }}
</body>

</html>


================================================
FILE: layouts/_default/list.html
================================================
{{ define "header" }}
{{ partialCached "header.html" . }}
{{ end }}

{{ define "main" }}
	<main class="site-main section-inner thin animated fadeIn faster">
		<h1>{{ .Title }}</h1>
		{{- if .Content }}
		<div class="content">
			{{ .Content }}
		</div>
		{{- end }}
		{{- range .Data.Pages.GroupByDate "2006" }}
		<div class="posts-group">
			<div class="post-year" id="{{ .Key }}">{{ .Key }}</div>
			<ul class="posts-list">
				{{- range .Pages }}
				<li class="post-item">
					<a href="{{.Permalink}}">
						<span class="post-title">{{.Title}}</span>
						<span class="post-day">{{ .Date.Format .Site.Params.dateformShort }}</span>
					</a>
				</li>
				{{- end }}
			</ul>
		</div>
		{{- end }}
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: layouts/_default/single.html
================================================
{{ define "head" }}
	{{ if .Params.featuredImg -}}
	<style>.bg-img {background-image: url('{{.Params.featuredImg}}');}</style>
	{{- else if .Params.images -}}
		{{- range first 1 .Params.images -}}
		<style>.bg-img {background-image: url('{{. | absURL}}');}</style>
		{{- end -}}
	{{- end -}}
{{ end }}

{{ define "header" }}
{{ partial "header.html" . }}
{{ end }}

{{ define "main" }}
	{{- if (or .Params.images .Params.featuredImg) }}
	<div class="bg-img"></div>
	{{- end }}
	<main class="site-main section-inner thin animated fadeIn faster">
		<h1>{{ .Title }}</h1>
		<div class="content">
			{{ .Content | replaceRE "(<h[1-6] id=\"([^\"]+)\".+)(</h[1-6]+>)" `${1}<a href="#${2}" class="anchor" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 7h3a5 5 0 0 1 5 5 5 5 0 0 1-5 5h-3m-6 0H6a5 5 0 0 1-5-5 5 5 0 0 1 5-5h3"></path><line x1="8" y1="12" x2="16" y2="12"></line></svg></a>${3}` | safeHTML }}
		</div>
		<div id="comments" class="thin">
			{{ partial "comments.html" . }}
		</div>
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: layouts/index.html
================================================
{{ define "header" }}
{{ partialCached "header.html" . }}
{{ end }}

{{ define "main" }}
		<main class="site-main section-inner thin animated fadeIn faster">
    {{ $paginator := .Paginate (where .Site.RegularPages "Type" "in" .Site.Params.mainSections) }}
		{{ range $paginator.Pages }}
        <div class="post animated fadeInDown">
            <div class="post-title">
                <h2><a href="{{ .RelPermalink }}">{{ .Title }}</a>
                </h2>
            </div>
            <div class="post-content">
                <div class="p_part"><p>{{ .Summary }}</p></div>
            </div>
            <div class="post-footer">
                <div class="meta">
                    <div class="info"><em class="fas fa-calendar-day"></em><span
                                class="date">{{ .Date.Format .Site.Params.dateformNum }}</span>
                        {{ with .Params.tags }}
                            {{- range $index, $el := . -}}
                                <a class="tag"
                                   href="{{ ( printf "tags/%s/" ( . | urlize ) ) | relLangURL }}">{{ . }}</a>
                            {{- end -}}
                        {{ end }}
                    </div>
                </div>
            </div>
				</div>
    {{ end }}
    <div class="pagination">
        {{ template "_internal/pagination.html" . }}
    </div>
		</main>
{{ end }}


{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: layouts/partials/analytics.html
================================================
{{ template "_internal/google_analytics_async.html" . }}


================================================
FILE: layouts/partials/comments.html
================================================
			<script src="https://utteranc.es/client.js"
							repo="eddycjy/blog"
							issue-term="pathname"
							theme="github-light"
							crossorigin="anonymous"
							async>
			</script>

================================================
FILE: layouts/partials/favicons.html
================================================
	<link rel="apple-touch-icon" sizes="180x180" href="{{"apple-touch-icon.png" | relURL}}">
	<link rel="icon" type="image/png" sizes="32x32" href="{{"favicon-32x32.png" | relURL}}">
	<link rel="icon" type="image/png" sizes="16x16" href="{{"favicon-16x16.png" | relURL}}">
	<link rel="manifest" href="{{"site.webmanifest" | relURL}}">
	<link rel="mask-icon" href="{{"safari-pinned-tab.svg" | relURL}}" color="{{.Site.Params.themeColor}}">
	<link rel="shortcut icon" href="{{"favicon.ico" | relURL}}">


================================================
FILE: layouts/partials/footer.html
================================================
	<footer id="site-footer" class="section-inner thin animated fadeIn faster">
		<p>&copy; 2018 - {{ now.Format "2006" }} <a href="{{ .Site.BaseURL }}">{{ .Site.Author.name }}</a>{{ .Site.Params.footerCopyright | safeHTML }}</p>
		<p>
			Made with <a href="https://gohugo.io/" target="_blank" rel="noopener">Hugo</a> &#183; Theme <a href="https://github.com/Track3/hermit" target="_blank" rel="noopener">Hermit</a>
			{{- with (not (in (.Site.Language.Get "disableKinds") "RSS")) }} &#183; <a href="{{ "posts/index.xml" | absURL }}" target="_blank" title="rss"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-rss"><path d="M4 11a9 9 0 0 1 9 9"></path><path d="M4 4a16 16 0 0 1 16 16"></path><circle cx="5" cy="19" r="1"></circle></svg></a>{{ end }}
		</p>
	</footer>

<script src="https://readmore.openwrite.cn/js/readmore.js" type="text/javascript"></script>
<script>
    const btw = new BTWPlugin();
    btw.init({
        id: 'articles',
        blogId: '15881-1622044386133-596',
        name: '脑子进煎鱼了',
        qrcode: 'https://image.eddycjy.com/7074be90379a121746146bc4229819f8.jpg',
        keyword: '666',
    });
</script>

================================================
FILE: layouts/partials/header.html
================================================
	<header id="site-header" class="animated slideInUp faster">
		<div class="hdr-wrapper section-inner">
			<div class="hdr-left">
				<div class="site-branding">
					<a href="{{.Site.BaseURL}}">{{ .Site.Title }}</a>
				</div>
				<nav class="site-nav hide-in-mobile">
					{{- range .Site.Menus.nav }}
					<a href="{{ .URL | absLangURL}}">{{ .Name }}</a>
					{{- end }}
				</nav>
			</div>
			<div class="hdr-right hdr-icons">
				{{ if (or .Params.images .Params.featuredImg) -}}
				<button id="img-btn" class="hdr-btn" title="{{i18n "featuredImage"}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-image"><rect x="3" y="3" width="18" height="18" rx="2" ry="2"></rect><circle cx="8.5" cy="8.5" r="1.5"></circle><polyline points="21 15 16 10 5 21"></polyline></svg></button>
				{{- end }}
				{{- with .Params.toc -}}
				<button id="toc-btn" class="hdr-btn desktop-only-ib" title="{{i18n "tableOfContents"}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-list"><line x1="8" y1="6" x2="21" y2="6"></line><line x1="8" y1="12" x2="21" y2="12"></line><line x1="8" y1="18" x2="21" y2="18"></line><line x1="3" y1="6" x2="3" y2="6"></line><line x1="3" y1="12" x2="3" y2="12"></line><line x1="3" y1="18" x2="3" y2="18"></line></svg></button>
				{{- end }}
				{{- with .Site.Params.social -}}
				<span class="hdr-social hide-in-mobile">{{ partialCached "social-icons.html" . }}</span>
				{{- end -}}
				<button id="menu-btn" class="hdr-btn" title="{{i18n "menu"}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"><line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line></svg></button>
			</div>
		</div>
	</header>
	<div id="mobile-menu" class="animated fast">
		<ul>
			{{- range .Site.Menus.main }}
			<li><a href="{{ .URL | absLangURL }}">{{ .Name }}</a></li>
			{{- end }}
		</ul>
	</div>


================================================
FILE: layouts/partials/social-icons.html
================================================
{{ range . -}}
<a href="{{ .url }}" target="_blank" rel="noopener me" title="{{ .name | humanize }}">{{ partial "svg.html" . }}</a>
{{- end -}}


================================================
FILE: layouts/partials/structured-data.html
================================================
{{/* We use some Hugo built-in templates, you can find their source here: */}}
{{/* https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates */}}

{{- template "_internal/schema.html" . }}
{{- template "_internal/opengraph.html" . }}
{{- template "_internal/twitter_cards.html" . }}


================================================
FILE: layouts/partials/svg.html
================================================
{{- if (eq .name "codepen") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-codepen"><polygon points="12 2 22 8.5 22 15.5 12 22 2 15.5 2 8.5 12 2"></polygon><line x1="12" y1="22" x2="12" y2="15.5"></line><polyline points="22 8.5 12 15.5 2 8.5"></polyline><polyline points="2 15.5 12 8.5 22 15.5"></polyline><line x1="12" y1="2" x2="12" y2="8.5"></line></svg>
{{- else if (eq .name "facebook") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-facebook"><path d="M18 2h-3a5 5 0 0 0-5 5v3H7v4h3v8h4v-8h3l1-4h-4V7a1 1 0 0 1 1-1h3z"></path></svg>
{{- else if (eq .name "github") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-github"><path d="M9 19c-5 1.5-5-2.5-7-3m14 6v-3.87a3.37 3.37 0 0 0-.94-2.61c3.14-.35 6.44-1.54 6.44-7A5.44 5.44 0 0 0 20 4.77 5.07 5.07 0 0 0 19.91 1S18.73.65 16 2.48a13.38 13.38 0 0 0-7 0C6.27.65 5.09 1 5.09 1A5.07 5.07 0 0 0 5 4.77a5.44 5.44 0 0 0-1.5 3.78c0 5.42 3.3 6.61 6.44 7A3.37 3.37 0 0 0 9 18.13V22"></path></svg>
{{- else if (eq .name "gitlab") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-gitlab"><path d="M22.65 14.39L12 22.13 1.35 14.39a.84.84 0 0 1-.3-.94l1.22-3.78 2.44-7.51A.42.42 0 0 1 4.82 2a.43.43 0 0 1 .58 0 .42.42 0 0 1 .11.18l2.44 7.49h8.1l2.44-7.51A.42.42 0 0 1 18.6 2a.43.43 0 0 1 .58 0 .42.42 0 0 1 .11.18l2.44 7.51L23 13.45a.84.84 0 0 1-.35.94z"></path></svg>
{{- else if (eq .name "instagram") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-instagram"><rect x="2" y="2" width="20" height="20" rx="5" ry="5"></rect><path d="M16 11.37A4 4 0 1 1 12.63 8 4 4 0 0 1 16 11.37z"></path><line x1="17.5" y1="6.5" x2="17.5" y2="6.5"></line></svg>
{{- else if (eq .name "linkedin") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-linkedin"><path d="M16 8a6 6 0 0 1 6 6v7h-4v-7a2 2 0 0 0-2-2 2 2 0 0 0-2 2v7h-4v-7a6 6 0 0 1 6-6z"></path><rect x="2" y="9" width="4" height="12"></rect><circle cx="4" cy="4" r="2"></circle></svg>
{{- else if (eq .name "slack") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-slack"><path d="M22.08 9C19.81 1.41 16.54-.35 9 1.92S-.35 7.46 1.92 15 7.46 24.35 15 22.08 24.35 16.54 22.08 9z"></path><line x1="12.57" y1="5.99" x2="16.15" y2="16.39"></line><line x1="7.85" y1="7.61" x2="11.43" y2="18.01"></line><line x1="16.39" y1="7.85" x2="5.99" y2="11.43"></line><line x1="18.01" y1="12.57" x2="7.61" y2="16.15"></line></svg>
{{- else if (eq .name "telegram") -}}
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" aria-hidden="true" class="feather"><path d="m 22.05,1.577 c -0.393,-0.016 -0.784,0.08 -1.117,0.235 -0.484,0.186 -4.92,1.902 -9.41,3.64 C 9.263,6.325 7.005,7.198 5.267,7.867 3.53,8.537 2.222,9.035 2.153,9.059 c -0.46,0.16 -1.082,0.362 -1.61,0.984 -0.79581202,1.058365 0.21077405,1.964825 1.004,2.499 1.76,0.564 3.58,1.102 5.087,1.608 0.556,1.96 1.09,3.927 1.618,5.89 0.174,0.394 0.553,0.54 0.944,0.544 l -0.002,0.02 c 0,0 0.307,0.03 0.606,-0.042 0.3,-0.07 0.677,-0.244 1.02,-0.565 0.377,-0.354 1.4,-1.36 1.98,-1.928 l 4.37,3.226 0.035,0.02 c 0,0 0.484,0.34 1.192,0.388 0.354,0.024 0.82,-0.044 1.22,-0.337 0.403,-0.294 0.67,-0.767 0.795,-1.307 0.374,-1.63 2.853,-13.427 3.276,-15.38 L 23.676,4.725 C 23.972,3.625 23.863,2.617 23.18,2.02 22.838,1.723 22.444,1.593 22.05,1.576 Z"></path></svg>
{{- else if (eq .name "twitter") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-twitter"><path d="M23 3a10.9 10.9 0 0 1-3.14 1.53 4.48 4.48 0 0 0-7.86 3v1A10.66 10.66 0 0 1 3 4s-4 9 5 13a11.64 11.64 0 0 1-7 2c9 5 20 0 20-11.5a4.5 4.5 0 0 0-.08-.83A7.72 7.72 0 0 0 23 3z"></path></svg>
{{- else if (eq .name "youtube") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-youtube"><path d="M22.54 6.42a2.78 2.78 0 0 0-1.94-2C18.88 4 12 4 12 4s-6.88 0-8.6.46a2.78 2.78 0 0 0-1.94 2A29 29 0 0 0 1 11.75a29 29 0 0 0 .46 5.33A2.78 2.78 0 0 0 3.4 19c1.72.46 8.6.46 8.6.46s6.88 0 8.6-.46a2.78 2.78 0 0 0 1.94-2 29 29 0 0 0 .46-5.25 29 29 0 0 0-.46-5.33z"></path><polygon points="9.75 15.02 15.5 11.75 9.75 8.48 9.75 15.02"></polygon></svg>
{{- else if (eq .name "email") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-mail"><path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"></path><polyline points="22,6 12,13 2,6"></polyline></svg>
{{- else -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
{{- end -}}


================================================
FILE: layouts/posts/rss.xml
================================================
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
		<link>{{ .Permalink }}</link>
		<description>Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
		<generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
		<language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
		<managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
		<webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
		<copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
		<lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
		{{ with .OutputFormats.Get "RSS" -}}
			{{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
		{{ end -}}
		{{ range .Pages }}
		<item>
			<title>{{ .Title }}</title>
			<link>{{ .Permalink }}</link>
			<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
			{{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
			<guid>{{ .Permalink }}</guid>
			<description>{{ .Summary | html }}</description>
			<content type="html">{{ printf `<![CDATA[%s]]>` .Content | safeHTML }}</content>
		</item>
		{{ end }}
	</channel>
</rss>


================================================
FILE: layouts/posts/single.html
================================================
{{ define "head" }}
	{{ if .Params.featuredImg -}}
	<style>.bg-img {background-image: url('{{.Params.featuredImg}}');}</style>
	{{- else if .Params.images -}}
		{{- range first 1 .Params.images -}}
		<style>.bg-img {background-image: url('{{. | absURL}}');}</style>
		{{- end -}}
	{{- end -}}
{{ end }}

{{ define "header" }}
{{ partial "header.html" . }}
{{ end }}

{{ define "main" }}
	{{- if (or .Params.images .Params.featuredImg) }}
	<div class="bg-img"></div>
	{{- end }}
	<main class="site-main section-inner animated fadeIn faster">
		<article id="articles" class="thin">
			<header class="post-header">
				<div class="post-meta"><span>{{ .Date.Format .Site.Params.dateform }}</span></div>
				<h1>{{ .Title }}</h1>
			</header>
			<div class="content">
				{{ .Content | replaceRE "(<h[1-6] id=\"([^\"]+)\".+)(</h[1-6]+>)" `${1}<a href="#${2}" class="anchor" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 7h3a5 5 0 0 1 5 5 5 5 0 0 1-5 5h-3m-6 0H6a5 5 0 0 1-5-5 5 5 0 0 1 5-5h3"></path><line x1="8" y1="12" x2="16" y2="12"></line></svg></a>${3}` | safeHTML }}
			</div>
			<div class="content"><br><img src="https://image.eddycjy.com/8c23cb407498f8446af59e43fb95ac62.png"></div>
			<hr class="post-end">
			<footer class="post-info">
				{{- with .Params.tags }}
				<p>
					<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-tag meta-icon"><path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z"></path><line x1="7" y1="7" x2="7" y2="7"></line></svg>
					{{- range . -}}
					<span class="tag"><a href="{{ "tags/" | absURL }}{{ . | urlize }}">{{.}}</a></span>
					{{- end }}
				</p>
				{{- end }}
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file-text"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path><polyline points="14 2 14 8 20 8"></polyline><line x1="16" y1="13" x2="8" y2="13"></line><line x1="16" y1="17" x2="8" y2="17"></line><polyline points="10 9 9 9 8 9"></polyline></svg>{{ i18n "wordCount" . }}</p>
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-calendar"><rect x="3" y="4" width="18" height="18" rx="2" ry="2"></rect><line x1="16" y1="2" x2="16" y2="6"></line><line x1="8" y1="2" x2="8" y2="6"></line><line x1="3" y1="10" x2="21" y2="10"></line></svg>{{ dateFormat .Site.Params.dateformNumTime .Date.Local }}</p>
				{{- if and .GitInfo .Site.Params.gitUrl }}
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-git-commit"><circle cx="12" cy="12" r="4"></circle><line x1="1.05" y1="12" x2="7" y2="12"></line><line x1="17.01" y1="12" x2="22.96" y2="12"></line></svg><a href="{{ .Site.Params.gitUrl -}}{{ .GitInfo.Hash }}" target="_blank" rel="noopener">{{ .GitInfo.AbbreviatedHash }}</a> @ {{ dateFormat .Site.Params.dateformNum .GitInfo.AuthorDate.Local }}</p>
				{{- end }}
			</footer>
		</article>
		{{- if .Params.toc }}
		<aside id="toc" class="show-toc">
			<div class="toc-title">{{ i18n "tableOfContents" }}</div>
			{{ .TableOfContents }}
		</aside>
		{{- end }}
		<div class="post-nav thin">
			{{- with .NextInSection }}
			<a class="next-post" href="{{ .Permalink }}">
				<span class="post-nav-label"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-arrow-left"><line x1="19" y1="12" x2="5" y2="12"></line><polyline points="12 19 5 12 12 5"></polyline></svg>&nbsp;{{ i18n "newer" }}</span><br><span>{{ .Title }}</span>
			</a>
			{{- end }}
			{{- with .PrevInSection }}
			<a class="prev-post" href="{{ .Permalink }}">
				<span class="post-nav-label">{{ i18n "older" }}&nbsp;<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-arrow-right"><line x1="5" y1="12" x2="19" y2="12"></line><polyline points="12 5 19 12 12 19"></polyline></svg></span><br><span>{{ .Title }}</span>
			</a>
			{{- end }}
		</div>
		<div id="comments" class="thin">
			{{ partialCached "comments.html" . }}
		</div>
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: resources/_gen/assets/scss/scss/style.scss_c16d144eee185fbddd582cd5e25a4fae.content
================================================
@charset "UTF-8";/*!normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css*/html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}button::-moz-focus-inner,[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}.chroma{color:#eee;background-color:#2c3e50}.chroma .err{color:#960050;background-color:#1e0010}.chroma .lntd{vertical-align:top;padding:0;margin:0;border:0}.chroma .lntable{border-spacing:0;padding:0;margin:0;border:0;width:auto;overflow:auto;display:block}.chroma .hl{display:block;width:100%;background-color:#ffc}.chroma .lnt{margin-right:.4em;padding:0 .4em}.chroma .ln{margin-right:.4em;padding:0 .4em}.chroma .k{color:#66d9ef}.chroma .kc{color:#66d9ef}.chroma .kd{color:#66d9ef}.chroma .kn{color:#f92672}.chroma .kp{color:#66d9ef}.chroma .kr{color:#66d9ef}.chroma .kt{color:#66d9ef}.chroma .na{color:#a6e22e}.chroma .nc{color:#a6e22e}.chroma .no{color:#66d9ef}.chroma .nd{color:#a6e22e}.chroma .ne{color:#a6e22e}.chroma .nf{color:#a6e22e}.chroma .nx{color:#a6e22e}.chroma .nt{color:#f92672}.chroma .l{color:#ae81ff}.chroma .ld{color:#e6db74}.chroma .s{color:#e6db74}.chroma .sa{color:#e6db74}.chroma .sb{color:#e6db74}.chroma .sc{color:#e6db74}.chroma .dl{color:#e6db74}.chroma .sd{color:#e6db74}.chroma .s2{color:#e6db74}.chroma .se{color:#ae81ff}.chroma .sh{color:#e6db74}.chroma .si{color:#e6db74}.chroma .sx{color:#e6db74}.chroma .sr{color:#e6db74}.chroma .s1{color:#e6db74}.chroma .ss{color:#e6db74}.chroma .m{color:#ae81ff}.chroma .mb{color:#ae81ff}.chroma .mf{color:#ae81ff}.chroma .mh{color:#ae81ff}.chroma .mi{color:#ae81ff}.chroma .il{color:#ae81ff}.chroma .mo{color:#ae81ff}.chroma .o{color:#f92672}.chroma .ow{color:#f92672}.chroma .c{color:#75715e}.chroma .ch{color:#75715e}.chroma .cm{color:#75715e}.chroma .c1{color:#75715e}.chroma .cs{color:#75715e}.chroma .cp{color:#75715e}.chroma .cpf{color:#75715e}.chroma .gd{color:#f92672}.chroma .ge{font-style:italic}.chroma .gi{color:#a6e22e}.chroma .gs{font-weight:700}.chroma .gu{color:#75715e}/*!* animate.css -https://daneden.github.io/animate.css/
* Version - 3.7.0
* Licensed under the MIT license - http://opensource.org/licenses/MIT
*
* Copyright (c) 2019 Daniel Eden*/@-webkit-keyframes flash{0%,50%,to{opacity:1}25%,75%{opacity:0}}@keyframes flash{0%,50%,to{opacity:1}25%,75%{opacity:0}}.flash{-webkit-animation-name:flash;animation-name:flash}@-webkit-keyframes bounceInRight{0%,60%,75%,90%,to{-webkit-animation-timing-function:cubic-bezier(0.215,0.61,0.355,1);animation-timing-function:cubic-bezier(0.215,0.61,0.355,1)}0%{opacity:0;-webkit-transform:translate3d(3000px,0,0);transform:translate3d(3000px,0,0)}60%{opacity:1;-webkit-transform:translate3d(-25px,0,0);transform:translate3d(-25px,0,0)}75%{-webkit-transform:translate3d(10px,0,0);transform:translate3d(10px,0,0)}90%{-webkit-transform:translate3d(-5px,0,0);transform:translate3d(-5px,0,0)}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}@keyframes bounceInRight{0%,60%,75%,90%,to{-webkit-animation-timing-function:cubic-bezier(0.215,0.61,0.355,1);animation-timing-function:cubic-bezier(0.215,0.61,0.355,1)}0%{opacity:0;-webkit-transform:translate3d(3000px,0,0);transform:translate3d(3000px,0,0)}60%{opacity:1;-webkit-transform:translate3d(-25px,0,0);transform:translate3d(-25px,0,0)}75%{-webkit-transform:translate3d(10px,0,0);transform:translate3d(10px,0,0)}90%{-webkit-transform:translate3d(-5px,0,0);transform:translate3d(-5px,0,0)}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}.bounceInRight{-webkit-animation-name:bounceInRight;animation-name:bounceInRight}@-webkit-keyframes bounceOutRight{20%{opacity:1;-webkit-transform:translate3d(-20px,0,0);transform:translate3d(-20px,0,0)}to{opacity:0;-webkit-transform:translate3d(2000px,0,0);transform:translate3d(2000px,0,0)}}@keyframes bounceOutRight{20%{opacity:1;-webkit-transform:translate3d(-20px,0,0);transform:translate3d(-20px,0,0)}to{opacity:0;-webkit-transform:translate3d(2000px,0,0);transform:translate3d(2000px,0,0)}}.bounceOutRight{-webkit-animation-name:bounceOutRight;animation-name:bounceOutRight}@-webkit-keyframes fadeIn{0%{opacity:0}to{opacity:1}}@keyframes fadeIn{0%{opacity:0}to{opacity:1}}.fadeIn{-webkit-animation-name:fadeIn;animation-name:fadeIn}@-webkit-keyframes slideInUp{0%{-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0);visibility:visible}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}@keyframes slideInUp{0%{-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0);visibility:visible}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}.slideInUp{-webkit-animation-name:slideInUp;animation-name:slideInUp}@-webkit-keyframes slideOutDown{0%{-webkit-transform:translateZ(0);transform:translateZ(0)}to{visibility:hidden;-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0)}}@keyframes slideOutDown{0%{-webkit-transform:translateZ(0);transform:translateZ(0)}to{visibility:hidden;-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0)}}.slideOutDown{-webkit-animation-name:slideOutDown;animation-name:slideOutDown}.animated{-webkit-animation-fill-mode:both;animation-fill-mode:both}.animated.infinite{-webkit-animation-iteration-count:infinite;animation-iteration-count:infinite}.animated.delay-1s{-webkit-animation-delay:1s;animation-delay:1s}.animated.delay-2s{-webkit-animation-delay:2s;animation-delay:2s}.animated.delay-3s{-webkit-animation-delay:3s;animation-delay:3s}.animated.delay-4s{-webkit-animation-delay:4s;animation-delay:4s}.animated.delay-5s{-webkit-animation-delay:5s;animation-delay:5s}.animated.fast{-webkit-animation-duration:.8s;animation-duration:.8s}.animated.slow{-webkit-animation-duration:2s;animation-duration:2s}.animated.slower{-webkit-animation-duration:3s;animation-duration:3s}@media(prefers-reduced-motion),(print){.animated{-webkit-animation:unset!important;animation:unset!important;-webkit-transition:none!important;transition:none!important}}::-webkit-scrollbar{width:8px;height:8px;background:#2c3e50}::-webkit-scrollbar-thumb{background:#888}::-webkit-scrollbar-thumb:hover{background:#3b3e48}html{background:#fcfcfc;line-height:1.6;letter-spacing:.05em;scroll-behavior:smooth}body,button,input,select,textarea{color:#3b3e48;font-family:trebuchet ms,Verdana,verdana ref,segoe ui,Candara,lucida grande,lucida sans unicode,lucida sans,Tahoma,sans-serif}pre,code,pre tt{font-family:Consolas,andale mono wt,andale mono,Menlo,Monaco,lucida console,lucida sans typewriter,dejavu sans mono,bitstream vera sans mono,liberation mono,nimbus mono l,courier new,Courier,yahei consolas hybrid,monospace,segoe ui emoji,pingfang sc,microsoft yahei}pre{padding:.7em 1.1em;overflow:auto;font-size:.9em;line-height:1.5;letter-spacing:normal;white-space:pre;color:#eee;background:#2c3e50;border-radius:4px}pre code{color:#eee;padding:0;margin:0;background:#2c3e50}code{color:#2c3e50;background:#eee;border-radius:3px;padding:0 3px;margin:0 4px;word-wrap:break-word;letter-spacing:normal}blockquote{border-left:.25em solid;margin:1em;padding:0 1em;font-style:italic}blockquote cite{font-weight:700;font-style:normal}blockquote cite::before{content:"—— "}a{color:#3b3e48;text-decoration:none;border:none;transition-property:color;transition-duration:.4s;transition-timing-function:ease-out}a:hover{color:#000}hr{opacity:.2;border-width:0 0 5px;border-style:dashed;background:0 0;width:50%;margin:1.8em auto}table{border-collapse:collapse;border-spacing:0;empty-cells:show;width:100%;max-width:100%}table th,table td{padding:1.5%;border:1px solid}table th{font-weight:700;vertical-align:bottom}.section-inner{margin:0 auto;max-width:1200px;width:93%}.thin{max-width:900px;margin:auto}.feather{display:inline-block;vertical-align:-.125em;width:1em;height:1em}.desktop-only,.desktop-only-ib{display:none}.screen-reader-text{border:0;clip:rect(1px,1px,1px,1px);clip-path:inset(50%);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute!important;width:1px;word-wrap:normal!important}.screen-reader-text:focus{background-color:#f1f1f1;border-radius:3px;box-shadow:0 0 2px 2px rgba(0,0,0,.6);clip:auto!important;clip-path:none;color:#21759b;display:block;font-size:14px;font-size:.875rem;font-weight:700;height:auto;left:5px;line-height:normal;padding:15px 23px 14px;text-decoration:none;top:5px;width:auto;z-index:100000}#site-header{z-index:1;width:100%;box-sizing:border-box;box-shadow:-1px 2px 3px rgba(0,0,0,.45);background-color:#f9f9f9}.hdr-wrapper{display:flex;justify-content:space-between;align-items:center;padding:.5em 0;font-size:1.2rem}.hdr-wrapper .site-branding{display:inline-block;margin-right:.8em;font-size:1.2em}.hdr-wrapper .site-nav{display:inline-block;font-size:1.1em;opacity:.8}.hdr-wrapper .site-nav a{margin-left:.8em}.hdr-icons{font-size:1.2em}.hdr-social{display:inline-block;margin-left:.6em}.hdr-social>a{margin-left:.4em}.hdr-btn{border:none;background:0 0;padding:0;margin-left:.4em;cursor:pointer}#menu-btn{display:none;margin-left:.6em;cursor:pointer}#mobile-menu{position:fixed;bottom:4.8em;right:1.5em;display:none;padding:.6em 1.8em;z-index:1;box-sizing:border-box;box-shadow:-1px -2px 3px 0 rgba(0,0,0,.45);background-color:#f9f9f9}#mobile-menu ul{list-style:none;margin:0;padding:0;line-height:2;font-size:1.2em}#site-footer{text-align:center;font-size:.9em;margin-bottom:96px;margin-top:64px}#site-footer p{margin:0}#spotlight{display:flex;height:100vh;flex-direction:column;align-items:center;justify-content:center;max-width:93%;margin:auto;font-size:1.5rem}#spotlight.error-404{flex-direction:row;line-height:normal}p.img-404{margin:0}p.img-404 svg{width:180px;max-width:100%;height:auto}.banner-404{margin-left:2em}.banner-404 h1{font-size:3em;margin:.5rem 0}.banner-404 p{margin-top:0}.banner-404 .btn-404{font-size:.8em}.banner-404 .btn-404 a{display:inline-block;border:2px solid #3b3e48;border-radius:5px;padding:5px;transition-property:color,border-color}.banner-404 .btn-404 a:first-child{margin-right:1em}.banner-404 .btn-404 a:hover{border-color:#000}.banner-404 .btn-404 a svg{margin-right:.5em}#home-center{display:flex;flex-grow:1;flex-direction:column;justify-content:center}#home-title{margin:0;text-align:center}#home-subtitle{margin-top:0;margin-bottom:1.5em;text-align:center;line-height:normal;font-size:.7em;font-style:italic;opacity:.9}#home-social{font-size:1.4em;text-align:center;opacity:.8}#home-social a{margin:0 .2em}#home-nav{opacity:.8}#home-nav a{display:block;text-align:center;margin-top:.5em}#home-footer{text-align:center;font-size:.6em;line-height:normal;opacity:.6}#home-footer p{margin-top:0}.posts-group{display:flex;margin-bottom:1.9em;line-height:normal}.posts-group .post-year{padding-top:6px;margin-right:1.8em;font-size:1.6em;opacity:.6}.posts-group .post-year:hover{text-decoration:underline;cursor:pointer}.posts-group .posts-list{flex-grow:1;margin:0;padding:0;list-style:none}.posts-group .post-item{border-bottom:1px #7d828a dashed}.posts-group .post-item a{display:flex;justify-content:space-between;align-items:baseline;padding:12px 0}.posts-group .post-day{flex-shrink:0;margin-left:1em;opacity:.6}.bg-img{width:100vw;height:100vh;opacity:.03;z-index:-1;position:fixed;top:0;background-attachment:fixed;background-repeat:no-repeat;background-size:cover;background-position:50%;transition:opacity .5s}.show-bg-img{z-index:100;opacity:1;cursor:pointer}.post-header{margin-top:1.2em;line-height:normal}.post-header .post-meta{font-size:.9em;letter-spacing:normal;opacity:.6}.post-header h1{margin-top:.1em}hr.post-end{width:50%;margin-top:1.6em;margin-bottom:.8em;margin-left:0;border-style:solid;border-bottom-width:4px}.content a{word-wrap:break-word;border:none;box-shadow:inset 0 -4px 0 #1ad1a3;transition-property:background-color}.content a:hover{background-color:#1ad1a3}.content figure{max-width:100%;height:auto;margin:0;text-align:center}.content figure p{font-size:.8em;font-style:italic;opacity:.6}.content figure.left{float:left;margin-right:1.5em;max-width:50%}.content figure.right{float:right;margin-left:1.5em;max-width:50%}.content figure.big{max-width:100vw}.content img{display:block;max-width:100%;height:auto;margin:auto;border-radius:4px}.content ul,.content ol{padding:0;margin-left:1.8em}.content a.anchor{float:left;margin-left:-20px;padding-right:6px;box-shadow:none;opacity:.8}.content a.anchor:hover{background:0 0;color:#1ad1a3;opacity:1}.content a.anchor svg{display:inline-block;width:14px;height:14px;vertical-align:baseline;visibility:hidden}.content a.anchor:focus svg{visibility:visible}.content h1:hover a.anchor svg,.content h2:hover a.anchor svg,.content h3:hover a.anchor svg,.content h4:hover a.anchor svg,.content h5:hover a.anchor svg,.content h6:hover a.anchor svg{visibility:visible}.footnotes{font-size:.85em}.footnotes a{box-shadow:none;text-decoration:underline;transition-property:color}.footnotes a:hover{background:0 0}.footnotes a.footnote-return{text-decoration:none}.footnotes ol{line-height:1.8}.footnote-ref a{box-shadow:none;text-decoration:none;padding:2px;border-radius:2px;background-color:#2c3e50}.post-info{font-size:.8rem;line-height:normal;opacity:.6}.post-info p{margin:.8em 0}.post-info a:hover{border-bottom:1px solid #1ad1a3}.post-info svg{margin-right:.8em}.post-info .tag{margin-right:.5em}.post-info .tag::before{content:"#"}#toc{position:fixed;left:50%;top:0;display:none}.toc-title{margin-left:1em;margin-bottom:.5em;font-size:.8em;font-weight:700}#TableOfContents{font-size:.8em;opacity:.6}#TableOfContents ul{padding-left:1em;margin:0}#TableOfContents>ul{list-style-type:none}#TableOfContents>ul ul ul{font-size:.9em}#TableOfContents a:hover{border-bottom:#1ad1a3 1px solid}.post-nav{display:flex;justify-content:space-between;margin-top:1.5em;margin-bottom:2.5em;font-size:1.2em}.post-nav a{flex-basis:50%;flex-grow:1}.post-nav .next-post{text-align:left;padding-right:5px}.post-nav .prev-post{text-align:right;padding-left:5px}.post-nav .post-nav-label{font-size:.8em;opacity:.8;text-transform:uppercase}@media(min-width:800px){.site-main{margin-top:3em}hr.post-end{width:40%}}@media(min-width:960px){.site-main{margin-top:6em}}@media(min-width:1300px){.site-main{margin-top:8em}.desktop-only,#toc.show-toc{display:block}.desktop-only-ib{display:inline-block}figure.left{margin-left:-240px}figure.left p{text-align:left}figure.right{margin-right:-240px}figure.right p{text-align:right}figure.big{width:1200px;margin-left:-240px}hr.post-end{width:30%}#toc{top:13em;margin-left:460px;max-width:220px}}@media(min-width:1800px){.site-main{margin-top:10em}.section-inner{max-width:1600px}.thin{max-width:960px}figure.left{max-width:75%;margin-left:-320px}figure.right{max-width:75%;margin-right:-320px}figure.big{width:1600px;margin-left:-320px}hr.post-end{width:30%}#toc{top:15em;margin-left:490px;max-width:300px}}@media(max-width:760px){.hide-in-mobile,.site-nav.hide-in-mobile{display:none}#menu-btn{display:inline-block}.posts-group{display:block}.posts-group .post-year{margin:-6px 0 4px}#spotlight.error-404{flex-direction:column;text-align:center}#spotlight.error-404 .banner-404{margin:0}}@media(max-width:520px){.content figure.left,.content figure.right{float:unset;max-width:100%;margin:0}hr.post-end{width:60%}#mobile-menu{right:1.2em}}.utterances{max-width:900px}

================================================
FILE: resources/_gen/assets/scss/scss/style.scss_c16d144eee185fbddd582cd5e25a4fae.json
================================================
{"Target":"css/style.min.d3141168199607bf3a517216ce3c263814eecdbc8fca72a9a88700799a838219.css","MediaType":"text/css","Data":{"Integrity":"sha256-0xQRaBmWB786UXIWzjwmOBTuzbyPynKpqIcAeZqDghk="}}

================================================
FILE: static/css/styles.css
================================================
:root {
    --bg-color: #fff;
    --secondary-bg-color: #eeeeee;
    --heading-color: #5f5f5f;
    --body-color: rgba(0, 0, 0, 0.7);
    --post-color: rgba(0, 0, 0, 0.44);
    --border-color: rgba(0, 0, 0, 0.15);
    --pre-bg-color: #f9f9fd;
    --nav-text-color: #5a5a5a;
    --tag-color: #424242;
    --blockquote-text-color: #858585;
    --blockquote-border-color: #dfe2e5;
    scroll-padding-top: 100px;
}

.post .post-footer {
    padding: 0 0 10px 0;
    border-bottom: 1px solid var(--border-color);
}

.post .post-footer .meta {
    max-width: 100%;
    display: flex;
    color: #bbbbbb;
}

.post .post-footer .meta .info {
    float: left;
    font-size: 12px;
    margin-bottom: 1em;
    color: var(--body-color);
}

.post .post-footer .info .separator a {
    margin-right: 0.2em;
}

.post .post-footer .meta .info .date {
    margin-right: 10px;
    margin-left: 5px
}

.info {
    margin: 1em;
}

.post .post-footer .meta a {
    text-decoration: none;
    color: var(--body-color);
    padding-right: 10px;
}

.post .post-footer .meta a:hover {
    color: #2660ab;
}

.post .post-footer .meta i {
    margin-right: 6px;
}

.post .post-footer .tags {
    padding-bottom: 15px;
    font-size: 13px;
}

.post .post-footer .tags ul {
    list-style-type: none;
    display: inline;
    margin: 0;
    padding: 0;
}

.post .post-footer .tags ul li {
    list-style-type: none;
    margin: 0;
    padding-right: 5px;
    display: inline;
}

.post .post-footer .tags a {
    text-decoration: none;
    color: var(--post-color);
    font-weight: 400;
}

.post .post-footer .tags a:hover {
    text-decoration: none;
}

.pagination {
    margin: 30px;
    padding: 0px 0 56px 0;
    text-align: center;
}

.pagination ul {
    list-style: none;
    margin: 0;
    padding: 0;
    height: 13px;
}

.pagination ul li {
    margin: 0 2px 0 2px;
    display: inline;
    line-height: 1;
}

.pagination ul li a {
    text-decoration: none;
    color: var(--body-color);
}

.pagination .pre {
    float: left;
}

.pagination .next {
    float: right;
}

.tag::before {
    content: "#";
    opacity: .5;
}

.tag {
    display: inline-block;
    font-size: 15px;
    line-height: 1;
    margin: 5px 8px 5px 0;
}


================================================
FILE: themes/hermit/.editorconfig
================================================
# editorconfig.org

root = true

[*]
charset = utf-8
indent_style = space
indent_size = 2
end_of_line = lf
insert_final_newline = true
trim_trailing_whitespace = true

[*.{html,xml}]
indent_style = tab

[*.md]
indent_style = unset
indent_size = unset
insert_final_newline = unset
trim_trailing_whitespace = unset


================================================
FILE: themes/hermit/.gitattributes
================================================
* text eol=lf
*.png binary


================================================
FILE: themes/hermit/LICENSE
================================================
The MIT License (MIT)

Copyright (c) 2018 Track3

Permission is hereby granted, free of charge, to any person obtaining a copy of
this software and associated documentation files (the "Software"), to deal in
the Software without restriction, including without limitation the rights to
use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of
the Software, and to permit persons to whom the Software is furnished to do so,
subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS
FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR
COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER
IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.


================================================
FILE: themes/hermit/README.md
================================================
# Hugo theme Hermit

[![Netlify Status](https://api.netlify.com/api/v1/badges/01a2e2de-d57d-4d89-8322-95685000e60f/deploy-status)](https://app.netlify.com/sites/hugo-theme-hermit/deploys)

Hermit is a minimal and fast theme for Hugo. It's built for bloggers who want a simple and focused website.

![](https://github.com/Track3/hermit/raw/master/images/screenshot.png)

## Features

* A single-column layout and carefully crafted typography offers a great reading experience.
* Navigations and functions are placed in the bottom bar which will hide when you scroll down.
* Featured image is supported. It will be displayed as a dimmed background of the page.
* Displays all of your posts on a single page, with one section per year, simple and compact.
* Extremely lightweight and load fast. No third party framework, no unnecessary code.
* Responsive & Retina Ready. Scales gracefully from a big screen all the way down to the smallest mobile phone. Assets in vector format ensures that it looks sharp on high-resolution screens.

**[Theme Demo](https://hugo-theme-hermit.netlify.com/)** (uses contents and config from the `exampleSite` folder)

![](https://github.com/Track3/hermit/raw/master/images/hermit.png)

## Getting started

### Installation

Run this command from the root of your Hugo directory:

```bash
$ git clone https://github.com/Track3/hermit.git themes/hermit
```

Or, if your Hugo site is already in git, you can include this repository as a [git submodule](https://git-scm.com/book/en/v2/Git-Tools-Submodules). This makes it easier to update this theme. For this you need to run:

```bash
$ git submodule add https://github.com/Track3/hermit.git themes/hermit
```

Alternatively, if you are not familiar with git, you can download the theme as a `.zip` file, unzip the theme contents, and then move the unzipped source into your `themes` directory.

For more information, read the official [documentation](https://gohugo.io/themes/installing-and-using-themes/) of Hugo.

### Configuration

The example config file can be found in the theme's `exampleSite` folder. You can just copy the `config.toml` to the root directory of your Hugo site. There are instructions in the example config file, feel free to change strings as you like to customize your website.

#### Favicon

Use [RealFaviconGenerator](https://realfavicongenerator.net/) to generate these files, put them into your site's `static` folder:

* android-chrome-192x192.png
* android-chrome-512x512.png
* apple-touch-icon.png
* favicon-16x16.png
* favicon-32x32.png
* favicon.ico
* mstile-150x150.png
* safari-pinned-tab.svg
* site.webmanifest

#### Social icons

The following icons are supported, please make sure the `name` filed is exactly one of these:

* codepen
* facebook
* github
* gitlab
* instagram
* linkedin
* slack
* telegram
* twitter
* youtube
* email

If that's not enough, you can see [Overriding templates](#overriding-templates) section.

### Manage content

* Keep your regular pages in the `content` folder. To create a new page, run `hugo new page-title.md`
* Keep your blog posts in the `content/posts` folder. To create a new post, run `hugo new posts/post-title.md`

### More customizations

#### Overriding templates

In Hugo, layouts can live in either the project’s (root) or the themes’ layout folders, any template inside the root layout folder will override theme's layout that relative to it, for example: `layouts/_default/baseof.html` will override `themes/hermit/layouts/_default/baseof.html`. So, you can easily customize the theme without edit it directly, which makes updating the theme easier. Here's some common customizations:

##### Customize social icons
You can modify or add any svg icons in site's `layouts/partials/svg.html`.

##### Customize comment system
We only have built-in support for Disqus at the moment, if that doesn't fit your needs, you can just add html to site's `layouts/partials/comments.html`.

##### Add custom analytics
If you prefer to use different analytics system other than google analytics, then add them inside `layouts/partials/analytics.html`.

#### Customize CSS

If you'd like to customize theme color or fonts, you can simply override `assets/scss/_predefined.scss`, by simply copy it to site's root (keep the same relative path) then edit those variables. But keep in mind, you'll need **Hugo extended version** which has the ability to rebuild SCSS. You don't have to use extended version in production but in this case it's necessary to make sure the `resources` folder is committed and "up to date" (by running `hugo` or `hugo server` locally using the extended version). But anyway, always use the extended version if you can.

For adding other custom CSS to the theme, you can assign an array of references in `config.toml` like following:
```
[params]
  customCSS = ["css/foo.css", "css/bar.css"]
```
You may reference as many stylesheets as you want. Their paths need to be relative to the `static` folder or it can be a full URL for external resources.

#### Code injection

You can inject any html code to every page's document head or right above the closing body tag. This makes it easier to add any html meta data, custom css/js, dns-prefetch etc. To do this you simply need to create a file at site's `layouts/partials/extra-head.html` or `layouts/partials/extra-foot.html`, code inside will be injected to every page.

## Acknowledgments

* [normalize.css](https://necolas.github.io/normalize.css/) - [MIT](https://github.com/necolas/normalize.css/blob/master/LICENSE.md)
* [animate.css](https://daneden.github.io/animate.css/) - [MIT](https://github.com/daneden/animate.css/blob/master/LICENSE)
* [feather](https://feathericons.com/) - [MIT](https://github.com/feathericons/feather/blob/master/LICENSE)

Thanks!


================================================
FILE: themes/hermit/archetypes/default.md
================================================
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
comments: false
images:
---



================================================
FILE: themes/hermit/archetypes/posts.md
================================================
---
title: "{{ replace .Name "-" " " | title }}"
date: {{ .Date }}
draft: true
toc: false
images:
tags: 
  - untagged
---



================================================
FILE: themes/hermit/assets/js/main.js
================================================
/**
 * Utils
 */

// Throttle
//
const throttle = (callback, limit) => {
  let timeoutHandler = null;
  return () => {
    if (timeoutHandler == null) {
      timeoutHandler = setTimeout(() => {
        callback();
        timeoutHandler = null;
      }, limit);
    }
  };
};

// addEventListener Helper
//
const listen = (ele, e, callback) => {
  if (document.querySelector(ele) !== null) {
    document.querySelector(ele).addEventListener(e, callback);
  }
}

/**
 * Functions
 */

// Auto Hide Header
//
let header = document.getElementById('site-header');
let lastScrollPosition = window.pageYOffset;

const autoHideHeader = () => {
  let currentScrollPosition = window.pageYOffset;
  if (currentScrollPosition > lastScrollPosition) {
    header.classList.remove('slideInUp');
    header.classList.add('slideOutDown');
  } else {
    header.classList.remove('slideOutDown');
    header.classList.add('slideInUp');
  }
  lastScrollPosition = currentScrollPosition;
}

// Mobile Menu Toggle
//
let mobileMenuVisible = false;

const toggleMobileMenu = () => {
  let mobileMenu = document.getElementById('mobile-menu');
  if (mobileMenuVisible == false) {
    mobileMenu.style.animationName = 'bounceInRight';
    mobileMenu.style.webkitAnimationName = 'bounceInRight';
    mobileMenu.style.display = 'block';
    mobileMenuVisible = true;
  } else {
    mobileMenu.style.animationName = 'bounceOutRight';
    mobileMenu.style.webkitAnimationName = 'bounceOutRight'
    mobileMenuVisible = false;
  }
}

// Featured Image Toggle
//
const showImg = () => {
  document.querySelector('.bg-img').classList.add('show-bg-img');
}

const hideImg = () => {
  document.querySelector('.bg-img').classList.remove('show-bg-img');
}

// ToC Toggle
//
const toggleToc = () => {
  document.getElementById('toc').classList.toggle('show-toc');
}


if (header !== null) {
  listen('#menu-btn', "click", toggleMobileMenu);
  listen('#toc-btn', "click", toggleToc);
  listen('#img-btn', "click", showImg);
  listen('.bg-img', "click", hideImg);

  document.querySelectorAll('.post-year').forEach((ele)=> {
    ele.addEventListener('click', () => {
      window.location.hash = '#' + ele.id;
    });
  });

  window.addEventListener('scroll', throttle(() => {
    autoHideHeader();

    if (mobileMenuVisible == true) {
      toggleMobileMenu();
    }
  }, 250));
}


================================================
FILE: themes/hermit/assets/scss/_animate.scss
================================================
@charset "UTF-8";

/*!
 * animate.css -https://daneden.github.io/animate.css/
 * Version - 3.7.0
 * Licensed under the MIT license - http://opensource.org/licenses/MIT
 *
 * Copyright (c) 2019 Daniel Eden
 */

@-webkit-keyframes flash{0%,50%,to{opacity:1}25%,75%{opacity:0}}@keyframes flash{0%,50%,to{opacity:1}25%,75%{opacity:0}}.flash{-webkit-animation-name:flash;animation-name:flash}@-webkit-keyframes bounceInRight{0%,60%,75%,90%,to{-webkit-animation-timing-function:cubic-bezier(.215,.61,.355,1);animation-timing-function:cubic-bezier(.215,.61,.355,1)}0%{opacity:0;-webkit-transform:translate3d(3000px,0,0);transform:translate3d(3000px,0,0)}60%{opacity:1;-webkit-transform:translate3d(-25px,0,0);transform:translate3d(-25px,0,0)}75%{-webkit-transform:translate3d(10px,0,0);transform:translate3d(10px,0,0)}90%{-webkit-transform:translate3d(-5px,0,0);transform:translate3d(-5px,0,0)}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}@keyframes bounceInRight{0%,60%,75%,90%,to{-webkit-animation-timing-function:cubic-bezier(.215,.61,.355,1);animation-timing-function:cubic-bezier(.215,.61,.355,1)}0%{opacity:0;-webkit-transform:translate3d(3000px,0,0);transform:translate3d(3000px,0,0)}60%{opacity:1;-webkit-transform:translate3d(-25px,0,0);transform:translate3d(-25px,0,0)}75%{-webkit-transform:translate3d(10px,0,0);transform:translate3d(10px,0,0)}90%{-webkit-transform:translate3d(-5px,0,0);transform:translate3d(-5px,0,0)}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}.bounceInRight{-webkit-animation-name:bounceInRight;animation-name:bounceInRight}@-webkit-keyframes bounceOutRight{20%{opacity:1;-webkit-transform:translate3d(-20px,0,0);transform:translate3d(-20px,0,0)}to{opacity:0;-webkit-transform:translate3d(2000px,0,0);transform:translate3d(2000px,0,0)}}@keyframes bounceOutRight{20%{opacity:1;-webkit-transform:translate3d(-20px,0,0);transform:translate3d(-20px,0,0)}to{opacity:0;-webkit-transform:translate3d(2000px,0,0);transform:translate3d(2000px,0,0)}}.bounceOutRight{-webkit-animation-name:bounceOutRight;animation-name:bounceOutRight}@-webkit-keyframes fadeIn{0%{opacity:0}to{opacity:1}}@keyframes fadeIn{0%{opacity:0}to{opacity:1}}.fadeIn{-webkit-animation-name:fadeIn;animation-name:fadeIn}@-webkit-keyframes slideInUp{0%{-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0);visibility:visible}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}@keyframes slideInUp{0%{-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0);visibility:visible}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}.slideInUp{-webkit-animation-name:slideInUp;animation-name:slideInUp}@-webkit-keyframes slideOutDown{0%{-webkit-transform:translateZ(0);transform:translateZ(0)}to{visibility:hidden;-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0)}}@keyframes slideOutDown{0%{-webkit-transform:translateZ(0);transform:translateZ(0)}to{visibility:hidden;-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0)}}.slideOutDown{-webkit-animation-name:slideOutDown;animation-name:slideOutDown}.animated{-webkit-animation-fill-mode:both;animation-fill-mode:both}.animated.infinite{-webkit-animation-iteration-count:infinite;animation-iteration-count:infinite}.animated.delay-1s{-webkit-animation-delay:1s;animation-delay:1s}.animated.delay-2s{-webkit-animation-delay:2s;animation-delay:2s}.animated.delay-3s{-webkit-animation-delay:3s;animation-delay:3s}.animated.delay-4s{-webkit-animation-delay:4s;animation-delay:4s}.animated.delay-5s{-webkit-animation-delay:5s;animation-delay:5s}.animated.fast{-webkit-animation-duration:.8s;animation-duration:.8s}.animated.faster{}.animated.slow{-webkit-animation-duration:2s;animation-duration:2s}.animated.slower{-webkit-animation-duration:3s;animation-duration:3s}@media (prefers-reduced-motion),(print){.animated{-webkit-animation:unset!important;animation:unset!important;-webkit-transition:none!important;transition:none!important}}

================================================
FILE: themes/hermit/assets/scss/_normalize.scss
================================================
/*! normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css */

/* Document
   ========================================================================== */

/**
 * 1. Correct the line height in all browsers.
 * 2. Prevent adjustments of font size after orientation changes in iOS.
 */

html {
  line-height: 1.15; /* 1 */
  -webkit-text-size-adjust: 100%; /* 2 */
}

/* Sections
   ========================================================================== */

/**
 * Remove the margin in all browsers.
 */

body {
  margin: 0;
}

/**
 * Correct the font size and margin on `h1` elements within `section` and
 * `article` contexts in Chrome, Firefox, and Safari.
 */

h1 {
  font-size: 2em;
  margin: 0.67em 0;
}

/* Grouping content
   ========================================================================== */

/**
 * 1. Add the correct box sizing in Firefox.
 * 2. Show the overflow in Edge and IE.
 */

hr {
  box-sizing: content-box; /* 1 */
  height: 0; /* 1 */
  overflow: visible; /* 2 */
}

/**
 * 1. Correct the inheritance and scaling of font size in all browsers.
 * 2. Correct the odd `em` font sizing in all browsers.
 */

pre {
  font-family: monospace, monospace; /* 1 */
  font-size: 1em; /* 2 */
}

/* Text-level semantics
   ========================================================================== */

/**
 * Remove the gray background on active links in IE 10.
 */

a {
  background-color: transparent;
}

/**
 * 1. Remove the bottom border in Chrome 57-
 * 2. Add the correct text decoration in Chrome, Edge, IE, Opera, and Safari.
 */

abbr[title] {
  border-bottom: none; /* 1 */
  text-decoration: underline; /* 2 */
  text-decoration: underline dotted; /* 2 */
}

/**
 * Add the correct font weight in Chrome, Edge, and Safari.
 */

b,
strong {
  font-weight: bolder;
}

/**
 * 1. Correct the inheritance and scaling of font size in all browsers.
 * 2. Correct the odd `em` font sizing in all browsers.
 */

code,
kbd,
samp {
  font-family: monospace, monospace; /* 1 */
  font-size: 1em; /* 2 */
}

/**
 * Add the correct font size in all browsers.
 */

small {
  font-size: 80%;
}

/**
 * Prevent `sub` and `sup` elements from affecting the line height in
 * all browsers.
 */

sub,
sup {
  font-size: 75%;
  line-height: 0;
  position: relative;
  vertical-align: baseline;
}

sub {
  bottom: -0.25em;
}

sup {
  top: -0.5em;
}

/* Embedded content
   ========================================================================== */

/**
 * Remove the border on images inside links in IE 10.
 */

img {
  border-style: none;
}

/* Forms
   ========================================================================== */

/**
 * 1. Change the font styles in all browsers.
 * 2. Remove the margin in Firefox and Safari.
 */

button,
input,
optgroup,
select,
textarea {
  font-family: inherit; /* 1 */
  font-size: 100%; /* 1 */
  line-height: 1.15; /* 1 */
  margin: 0; /* 2 */
}

/**
 * Show the overflow in IE.
 * 1. Show the overflow in Edge.
 */

button,
input { /* 1 */
  overflow: visible;
}

/**
 * Remove the inheritance of text transform in Edge, Firefox, and IE.
 * 1. Remove the inheritance of text transform in Firefox.
 */

button,
select { /* 1 */
  text-transform: none;
}

/**
 * Correct the inability to style clickable types in iOS and Safari.
 */

button,
[type="button"],
[type="reset"],
[type="submit"] {
  -webkit-appearance: button;
}

/**
 * Remove the inner border and padding in Firefox.
 */

button::-moz-focus-inner,
[type="button"]::-moz-focus-inner,
[type="reset"]::-moz-focus-inner,
[type="submit"]::-moz-focus-inner {
  border-style: none;
  padding: 0;
}

/**
 * Restore the focus styles unset by the previous rule.
 */

button:-moz-focusring,
[type="button"]:-moz-focusring,
[type="reset"]:-moz-focusring,
[type="submit"]:-moz-focusring {
  outline: 1px dotted ButtonText;
}

/**
 * Correct the padding in Firefox.
 */

fieldset {
  padding: 0.35em 0.75em 0.625em;
}

/**
 * 1. Correct the text wrapping in Edge and IE.
 * 2. Correct the color inheritance from `fieldset` elements in IE.
 * 3. Remove the padding so developers are not caught out when they zero out
 *    `fieldset` elements in all browsers.
 */

legend {
  box-sizing: border-box; /* 1 */
  color: inherit; /* 2 */
  display: table; /* 1 */
  max-width: 100%; /* 1 */
  padding: 0; /* 3 */
  white-space: normal; /* 1 */
}

/**
 * Add the correct vertical alignment in Chrome, Firefox, and Opera.
 */

progress {
  vertical-align: baseline;
}

/**
 * Remove the default vertical scrollbar in IE 10+.
 */

textarea {
  overflow: auto;
}

/**
 * 1. Add the correct box sizing in IE 10.
 * 2. Remove the padding in IE 10.
 */

[type="checkbox"],
[type="radio"] {
  box-sizing: border-box; /* 1 */
  padding: 0; /* 2 */
}

/**
 * Correct the cursor style of increment and decrement buttons in Chrome.
 */

[type="number"]::-webkit-inner-spin-button,
[type="number"]::-webkit-outer-spin-button {
  height: auto;
}

/**
 * 1. Correct the odd appearance in Chrome and Safari.
 * 2. Correct the outline style in Safari.
 */

[type="search"] {
  -webkit-appearance: textfield; /* 1 */
  outline-offset: -2px; /* 2 */
}

/**
 * Remove the inner padding in Chrome and Safari on macOS.
 */

[type="search"]::-webkit-search-decoration {
  -webkit-appearance: none;
}

/**
 * 1. Correct the inability to style clickable types in iOS and Safari.
 * 2. Change font properties to `inherit` in Safari.
 */

::-webkit-file-upload-button {
  -webkit-appearance: button; /* 1 */
  font: inherit; /* 2 */
}

/* Interactive
   ========================================================================== */

/*
 * Add the correct display in Edge, IE 10+, and Firefox.
 */

details {
  display: block;
}

/*
 * Add the correct display in all browsers.
 */

summary {
  display: list-item;
}

/* Misc
   ========================================================================== */

/**
 * Add the correct display in IE 10+.
 */

template {
  display: none;
}

/**
 * Add the correct display in IE 10.
 */

[hidden] {
  display: none;
}

================================================
FILE: themes/hermit/assets/scss/_predefined.scss
================================================
// Colors
//
// Dark theme
//$theme: #018574;
//$text: #c6cddb;
//$light-grey: #494f5c;
//$dark-grey: #3B3E48;
//$highlight-grey: #7d828a;
//$midnightblue: #2c3e50;

$theme: #1ad1a3;
$text: #3b3e48;
$light-grey: #fcfcfc;
$dark-grey: #f9f9f9;
$highlight-grey: #7d828a;
$midnightblue: #2c3e50;

// Fonts
//
$fonts: "Trebuchet MS", Verdana, "Verdana Ref", "Segoe UI", Candara, "Lucida Grande", "Lucida Sans Unicode", "Lucida Sans", Tahoma, sans-serif;
$code-fonts: Consolas, "Andale Mono WT", "Andale Mono", Menlo, Monaco, "Lucida Console", "Lucida Sans Typewriter", "DejaVu Sans Mono", "Bitstream Vera Sans Mono", "Liberation Mono", "Nimbus Mono L", "Courier New", Courier, "YaHei Consolas Hybrid", monospace, "Segoe UI Emoji", "PingFang SC", "Microsoft YaHei";

// Mixins
//
@mixin dimmed {
  opacity: .6;
}

@mixin aTag {
  a {
    word-wrap: break-word;
    border: none;
    box-shadow: inset 0 -4px 0 $theme;
    transition-property: background-color;

    &:hover {
      background-color: $theme;
    }
  }
}


================================================
FILE: themes/hermit/assets/scss/_syntax.scss
================================================
/* Background */ .chroma { color: #eee; background-color: $midnightblue }
/* Error */ .chroma .err { color: #960050; background-color: #1e0010 }
/* LineTableTD */ .chroma .lntd { vertical-align: top; padding: 0; margin: 0; border: 0; }
/* LineTable */ .chroma .lntable { border-spacing: 0; padding: 0; margin: 0; border: 0; width: auto; overflow: auto; display: block; }
/* LineHighlight */ .chroma .hl { display: block; width: 100%;background-color: #ffffcc }
/* LineNumbersTable */ .chroma .lnt { margin-right: 0.4em; padding: 0 0.4em 0 0.4em; }
/* LineNumbers */ .chroma .ln { margin-right: 0.4em; padding: 0 0.4em 0 0.4em; }
/* Keyword */ .chroma .k { color: #66d9ef }
/* KeywordConstant */ .chroma .kc { color: #66d9ef }
/* KeywordDeclaration */ .chroma .kd { color: #66d9ef }
/* KeywordNamespace */ .chroma .kn { color: #f92672 }
/* KeywordPseudo */ .chroma .kp { color: #66d9ef }
/* KeywordReserved */ .chroma .kr { color: #66d9ef }
/* KeywordType */ .chroma .kt { color: #66d9ef }
/* NameAttribute */ .chroma .na { color: #a6e22e }
/* NameClass */ .chroma .nc { color: #a6e22e }
/* NameConstant */ .chroma .no { color: #66d9ef }
/* NameDecorator */ .chroma .nd { color: #a6e22e }
/* NameException */ .chroma .ne { color: #a6e22e }
/* NameFunction */ .chroma .nf { color: #a6e22e }
/* NameOther */ .chroma .nx { color: #a6e22e }
/* NameTag */ .chroma .nt { color: #f92672 }
/* Literal */ .chroma .l { color: #ae81ff }
/* LiteralDate */ .chroma .ld { color: #e6db74 }
/* LiteralString */ .chroma .s { color: #e6db74 }
/* LiteralStringAffix */ .chroma .sa { color: #e6db74 }
/* LiteralStringBacktick */ .chroma .sb { color: #e6db74 }
/* LiteralStringChar */ .chroma .sc { color: #e6db74 }
/* LiteralStringDelimiter */ .chroma .dl { color: #e6db74 }
/* LiteralStringDoc */ .chroma .sd { color: #e6db74 }
/* LiteralStringDouble */ .chroma .s2 { color: #e6db74 }
/* LiteralStringEscape */ .chroma .se { color: #ae81ff }
/* LiteralStringHeredoc */ .chroma .sh { color: #e6db74 }
/* LiteralStringInterpol */ .chroma .si { color: #e6db74 }
/* LiteralStringOther */ .chroma .sx { color: #e6db74 }
/* LiteralStringRegex */ .chroma .sr { color: #e6db74 }
/* LiteralStringSingle */ .chroma .s1 { color: #e6db74 }
/* LiteralStringSymbol */ .chroma .ss { color: #e6db74 }
/* LiteralNumber */ .chroma .m { color: #ae81ff }
/* LiteralNumberBin */ .chroma .mb { color: #ae81ff }
/* LiteralNumberFloat */ .chroma .mf { color: #ae81ff }
/* LiteralNumberHex */ .chroma .mh { color: #ae81ff }
/* LiteralNumberInteger */ .chroma .mi { color: #ae81ff }
/* LiteralNumberIntegerLong */ .chroma .il { color: #ae81ff }
/* LiteralNumberOct */ .chroma .mo { color: #ae81ff }
/* Operator */ .chroma .o { color: #f92672 }
/* OperatorWord */ .chroma .ow { color: #f92672 }
/* Comment */ .chroma .c { color: #75715e }
/* CommentHashbang */ .chroma .ch { color: #75715e }
/* CommentMultiline */ .chroma .cm { color: #75715e }
/* CommentSingle */ .chroma .c1 { color: #75715e }
/* CommentSpecial */ .chroma .cs { color: #75715e }
/* CommentPreproc */ .chroma .cp { color: #75715e }
/* CommentPreprocFile */ .chroma .cpf { color: #75715e }
/* GenericDeleted */ .chroma .gd { color: #f92672 }
/* GenericEmph */ .chroma .ge { font-style: italic }
/* GenericInserted */ .chroma .gi { color: #a6e22e }
/* GenericStrong */ .chroma .gs { font-weight: bold }
/* GenericSubheading */ .chroma .gu { color: #75715e }


================================================
FILE: themes/hermit/assets/scss/style.scss
================================================
@import "predefined.scss";
@import "normalize.scss";
@import "syntax.scss";
@import "animate.scss";

/* Webkit Scrollbar Customize */
::-webkit-scrollbar {
  width: 8px;
  height: 8px;
  background: $midnightblue;
}

::-webkit-scrollbar-thumb {
  background: #888;

  &:hover {
    background: $text;
  }
}

html {
  background: $light-grey;
  line-height: 1.6;
  letter-spacing: .05em;
  scroll-behavior: smooth;
}

body,
button,
input,
select,
textarea {
  color: $text;
  font-family: $fonts;
}

pre,
code,
pre tt {
  font-family: $code-fonts;
}

pre {
  padding: .7em 1.1em;
  overflow: auto;
  font-size: .9em;
  line-height: 1.5;
  letter-spacing: normal;
  white-space: pre;
  color: #eee;
  background: $midnightblue;
  border-radius: 4px;
  // -webkit-overflow-scrolling: touch;

  code {
    color: #eee;
    padding: 0;
    margin: 0;
    background: $midnightblue;
  }
}

code {
  color: $midnightblue;
  background: #eee;
  border-radius: 3px;
  padding: 0 3px;
  margin: 0 4px;
  word-wrap: break-word;
  letter-spacing: normal;
}

blockquote {
  border-left: .25em solid;
  margin: 1em;
  padding: 0 1em;
  font-style: italic;

  cite {
    font-weight: bold;
    font-style: normal;

    &::before {
      content: "—— ";
    }
  }
}

a {
  color: $text;
  text-decoration: none;
  border: none;
  transition-property: color;
  transition-duration: .4s;
  transition-timing-function: ease-out;

  &:hover {
    color: #000000;
  }
}

hr {
  opacity: .2;
  border-width: 0 0 5px 0;
  border-style: dashed;
  background: transparent;
  width: 50%;
  margin: 1.8em auto;
}

table {
  border-collapse: collapse;
  border-spacing: 0;
  empty-cells: show;
  width: 100%;
  max-width: 100%;

  th,
  td {
    padding: 1.5%;
    border: 1px solid;
  }

  th {
    font-weight: 700;
    vertical-align: bottom;
  }
}

.section-inner {
  margin: 0 auto;
  max-width: 1200px;
  width: 93%;
}

.thin {
  max-width: 900px;
  margin: auto;
}

.feather {
  display: inline-block;
  vertical-align: -.125em;
  width: 1em;
  height: 1em;
}

.desktop-only, .desktop-only-ib {
  display: none;
}

// Accessibility
//
.screen-reader-text {
	border: 0;
	clip: rect(1px, 1px, 1px, 1px);
	clip-path: inset(50%);
	height: 1px;
	margin: -1px;
	overflow: hidden;
	padding: 0;
	position: absolute !important;
	width: 1px;
	word-wrap: normal !important;
}

.screen-reader-text:focus {
	background-color: #f1f1f1;
	border-radius: 3px;
	box-shadow: 0 0 2px 2px rgba(0, 0, 0, 0.6);
	clip: auto !important;
	clip-path: none;
	color: #21759b;
	display: block;
	font-size: 14px;
	font-size: 0.875rem;
	font-weight: bold;
	height: auto;
	left: 5px;
	line-height: normal;
	padding: 15px 23px 14px;
	text-decoration: none;
	top: 5px;
	width: auto;
	z-index: 100000;
}

// Header & Footer
//
#site-header {
  //position: fixed;
  z-index: 1;
  //bottom: 0;
  width: 100%;
  box-sizing: border-box;
  box-shadow: -1px 2px 3px rgba(0, 0, 0, 0.45);
  background-color: $dark-grey;
}

.hdr-wrapper {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: .5em 0;
  font-size: 1.2rem;

  .site-branding {
    display: inline-block;
    margin-right: .8em;
    font-size: 1.2em;
  }

  .site-nav {
    display: inline-block;
    font-size: 1.1em;
    opacity: .8;

    a {
      margin-left: .8em;
    }
  }
}

.hdr-icons {
  font-size: 1.2em;
}

.hdr-social {
  display: inline-block;
  margin-left: .6em;

  &>a {
    margin-left: .4em;
  }
}

.hdr-btn {
  border: none;
  background: none;
  padding: 0;
  margin-left: .4em;
  cursor: pointer;
}

#menu-btn {
  display: none;
  margin-left: .6em;
  cursor: pointer;
}

#mobile-menu {
  position: fixed;
  bottom: 4.8em;
  right: 1.5em;
  display: none;
  padding: .6em 1.8em;
  z-index: 1;
  box-sizing: border-box;
  box-shadow: -1px -2px 3px 0px rgba(0, 0, 0, 0.45);
  background-color: $dark-grey;

  ul {
    list-style: none;
    margin: 0;
    padding: 0;
    line-height: 2;
    font-size: 1.2em;
  }
}

#site-footer {
  text-align: center;
  font-size: .9em;
  margin-bottom: 96px;
  margin-top: 64px;

  p {
    margin: 0;
  }
}

// Spotlight
//
#spotlight {
  display: flex;
  height: 100vh;
  flex-direction: column;
  align-items: center;
  justify-content: center;
  max-width: 93%;
  margin: auto;
  font-size: 1.5rem;

  &.error-404 {
    flex-direction: row;
    line-height: normal;
  }
}

p.img-404 {
  margin: 0;

  svg {
    width: 180px;
    max-width: 100%;
    height: auto;
  }
}

.banner-404 {
  margin-left: 2em;

  h1 {
    font-size: 3em;
    margin: .5rem 0;
  }

  p {
    margin-top: 0;
  }

  .btn-404 {
    font-size: .8em;

    a {
      display: inline-block;
      border: 2px solid $text;
      border-radius: 5px;
      padding: 5px;
      transition-property: color, border-color;

      &:first-child {
        margin-right: 1em;
      }

      &:hover {
        border-color: #000000;
      }

      svg {
        margin-right: .5em;
      }
    }
  }
}

#home-center {
  display: flex;
  flex-grow: 1;
  flex-direction: column;
  justify-content: center;
}

#home-title {
  margin: 0;
  text-align: center;
}

#home-subtitle {
  margin-top: 0;
  margin-bottom: 1.5em;
  text-align: center;
  line-height: normal;
  font-size: .7em;
  font-style: italic;
  opacity: .9;
}

#home-social {
  font-size: 1.4em;
  text-align: center;
  opacity: .8;

  a {
    margin: 0 .2em;
  }
}

#home-nav {
  opacity: .8;

  a {
    display: block;
    text-align: center;
    margin-top: .5em;
  }
}

#home-footer {
  text-align: center;
  font-size: .6em;
  line-height: normal;
  @include dimmed;

  p {
    margin-top: 0;
  }
}

// list.html
//
.posts-group {
  display: flex;
  margin-bottom: 1.9em;
  line-height: normal;

  .post-year {
    padding-top: 6px;
    margin-right: 1.8em;
    font-size: 1.6em;
    @include dimmed;

    &:hover {
      text-decoration: underline;
      cursor: pointer;
    }
  }

  .posts-list {
    flex-grow: 1;
    margin: 0;
    padding: 0;
    list-style: none;
  }

  .post-item {
    border-bottom: 1px $highlight-grey dashed;

    a {
      display: flex;
      justify-content: space-between;
      align-items: baseline;
      padding: 12px 0;
    }
  }

  .post-day {
    flex-shrink: 0;
    margin-left: 1em;
    @include dimmed;
  }
}

// single.html
//
.bg-img {
  width: 100vw;
  height: 100vh;
  opacity: .03;
  z-index: -1;
  position: fixed;
  top: 0;
  background-attachment: fixed;
  background-repeat: no-repeat;
  background-size: cover;
  background-position: center;
  transition: opacity .5s;
}

.show-bg-img {
  z-index: 100;
  opacity: 1;
  cursor: pointer;
}

.post-header {
  margin-top: 1.2em;
  line-height: normal;

  .post-meta {
    font-size: .9em;
    letter-spacing: normal;
    @include dimmed;
  }

  h1 {
    margin-top: .1em;
  }
}

hr.post-end {
  width: 50%;
  margin-top: 1.6em;
  margin-bottom: .8em;
  margin-left: 0;
  border-style: solid;
  border-bottom-width: 4px;
}

.content {
  {{- with .Site.Params.justifyContent }}
  text-align: justify;
  text-justify: inter-ideograph; //For IE/Edge
  {{- end }}

  @include aTag;

  figure {
    max-width: 100%;
    height: auto;
    margin: 0;
    text-align: center;

    p {
      font-size: .8em;
      font-style: italic;
      @include dimmed;
    }
  }

  figure.left {
    float: left;
    margin-right: 1.5em;
    max-width: 50%;
  }

  figure.right {
    float: right;
    margin-left: 1.5em;
    max-width: 50%;
  }

  figure.big {
    max-width: 100vw;
  }

  img {
    display: block;
    max-width: 100%;
    height: auto;
    margin: auto;
    border-radius: 4px;
  }

  ul,
  ol {
    padding: 0;
    margin-left: 1.8em;
  }

  a.anchor {
    float: left;
    margin-left: -20px;
    padding-right: 6px;
    box-shadow: none;
    opacity: .8;
    &:hover {
      background: none;
      color: $theme;
      opacity: 1;
    }

    svg {
      display: inline-block;
      width: 14px;
      height: 14px;
      vertical-align: baseline;
      visibility: hidden;
    }
    &:focus svg {
      visibility: visible;
    }
  }

  h1:hover a.anchor svg,
  h2:hover a.anchor svg,
  h3:hover a.anchor svg,
  h4:hover a.anchor svg,
  h5:hover a.anchor svg,
  h6:hover a.anchor svg {
    visibility: visible;
  }
}

.footnotes {
  font-size: .85em;

  a {
    box-shadow: none;
    text-decoration: underline;
    transition-property: color;

    &:hover {
      background: transparent;
    }

    &.footnote-return {
      text-decoration: none;
    }
  }

  ol {
    line-height: 1.8;
  }
}

.footnote-ref a {
  box-shadow: none;
  text-decoration: none;
  padding: 2px;
  border-radius: 2px;
  background-color: $midnightblue;
}

.post-info {
  font-size: .8rem;
  line-height: normal;
  @include dimmed;

  p {
    margin: .8em 0;
  }

  a:hover {
    border-bottom: 1px solid $theme;
  }

  svg {
    margin-right: .8em;
  }

  .tag {
    margin-right: .5em;

    &::before {
      content: "#"
    }
  }
}

#toc {
  position: fixed;
  left: 50%;
  top: 0;
  display: none;
}

.toc-title {
  margin-left: 1em;
  margin-bottom: .5em;
  font-size: .8em;
  font-weight: bold;
}

#TableOfContents {
  font-size: .8em;
  @include dimmed;

  ul {
    padding-left: 1em;
    margin: 0;
  }

  &>ul {
    list-style-type: none;

    ul ul {
      font-size: .9em;
    }
  }

  a:hover {
    border-bottom: $theme 1px solid;
  }
}


.post-nav {
  display: flex;
  justify-content: space-between;
  margin-top: 1.5em;
  margin-bottom: 2.5em;
  font-size: 1.2em;

  a {
    flex-basis: 50%;
    flex-grow: 1;
  }

  .next-post {text-align: left; padding-right: 5px;}
  .prev-post {text-align: right; padding-left: 5px;}

  .post-nav-label {
    font-size: .8em;
    opacity: .8;
    text-transform: uppercase;
  }
}

// Media Queries
//
@media (min-width: 800px) {
  .site-main {
    margin-top: 3em;
  }

  hr.post-end {
    width: 40%;
  }
}

@media (min-width: 960px) {
  .site-main {
    margin-top: 6em;
  }
}

@media (min-width: 1300px) {
  .site-main {
    margin-top: 8em;
  }

  .desktop-only,
  #toc.show-toc {
    display: block;
  }

  .desktop-only-ib {
    display: inline-block;
  }

  figure.left {
    margin-left: -240px;
    p {
      text-align: left;
    }
  }

  figure.right {
    margin-right: -240px;
    p {
      text-align: right;
    }
  }

  figure.big {
    width: 1200px;
    margin-left: -240px;
  }

  hr.post-end {
    width: 30%;
  }

  #toc {
    top: 13em;
    margin-left: 460px;
    max-width: 220px;
  }
}

@media (min-width: 1800px) {
  .site-main {
    margin-top: 10em;
  }

  .section-inner {
    max-width: 1600px;
  }

  .thin {
    max-width: 960px;
  }

  figure.left {
    max-width: 75%;
    margin-left: -320px;
  }

  figure.right {
    max-width: 75%;
    margin-right: -320px;
  }

  figure.big {
    width: 1600px;
    margin-left: -320px;
  }

  hr.post-end {
    width: 30%;
  }

  #toc {
    top: 15em;
    margin-left: 490px;
    max-width: 300px;
  }
}

@media (max-width: 760px) {

  .hide-in-mobile,
  .site-nav.hide-in-mobile {
    display: none;
  }

  #menu-btn {
    display: inline-block;
  }

  .posts-group {
    display: block;

    .post-year {
      margin: -6px 0 4px;
    }
  }

  #spotlight.error-404 {
    flex-direction: column;
    text-align: center;

    .banner-404 {
      margin: 0;
    }
  }
}

@media (max-width: 520px) {

  .content figure.left,
  .content figure.right {
    float: unset;
    max-width: 100%;
    margin: 0;
  }

  hr.post-end {
    width: 60%;
  }

  #mobile-menu {
    right: 1.2em;
  }
}

.utterances {
  max-width: 900px;
}


================================================
FILE: themes/hermit/exampleSite/config.toml
================================================
baseURL = "https://example.com"
languageCode = "en-us"
defaultContentLanguage = "en"
title = "Hugo Hermit"
theme = "hermit"
# enableGitInfo = true
pygmentsCodefences  = true
pygmentsUseClasses  = true
# hasCJKLanguage = true  # If Chinese/Japanese/Korean is your main content language, enable this to make wordCount works right.
rssLimit = 10  # Maximum number of items in the RSS feed.
copyright = "This work is licensed under a Creative Commons Attribution-NonCommercial 4.0 International License." # This message is only used by the RSS template.
enableEmoji = true  # Shorthand emojis in content files - https://gohugo.io/functions/emojify/
# googleAnalytics = "UA-123-45"
# disqusShortname = "yourdiscussshortname"

[author]
  name = "John Doe"

[blackfriday]
  # hrefTargetBlank = true
  # noreferrerLinks = true
  # nofollowLinks = true

[taxonomies]
  tag = "tags"
  # Categories are disabled by default.

[params]
  dateform        = "Jan 2, 2006"
  dateformShort   = "Jan 2"
  dateformNum     = "2006-01-02"
  dateformNumTime = "2006-01-02 15:04 -0700"

  # Metadata mostly used in document's head
  # description = ""
  # images = [""]
  themeColor = "#494f5c"

  homeSubtitle = "A minimal and fast theme for Hugo."
  footerCopyright = ' &#183; <a href="https://creativecommons.org/licenses/by-nc/4.0/" target="_blank" rel="noopener">CC BY-NC 4.0</a>'
  # bgImg = ""  # Homepage background-image URL

  # Prefix of link to the git commit detail page. GitInfo must be enabled.
  # gitUrl = "https://github.com/username/repository/commit/"

  # Toggling this option needs to rebuild SCSS, requires Hugo extended version
  justifyContent = false  # Set "text-align: justify" to `.content`.

  # Add custom css
  # customCSS = ["css/foo.css", "css/bar.css"]

  # Social Icons
  # Check https://github.com/Track3/hermit#social-icons for more info.
  [[params.social]]
    name = "twitter"
    url = "https://twitter.com/"

  [[params.social]]
    name = "instagram"
    url = "https://instagram.com/"

  [[params.social]]
    name = "github"
    url = "https://github.com/"

[menu]

  [[menu.main]]
    name = "Posts"
    url = "posts/"
    weight = 10

  [[menu.main]]
    name = "About"
    url = "about-hugo/"
    weight = 20


================================================
FILE: themes/hermit/exampleSite/content/about-hugo.md
================================================
+++
title = "About Hugo"
date = "2014-04-09"
+++

Hugo is the **world’s fastest framework for building websites**. It is written in Go.

It makes use of a variety of open source projects including:

* https://github.com/russross/blackfriday
* https://github.com/alecthomas/chroma
* https://github.com/muesli/smartcrop
* https://github.com/spf13/cobra
* https://github.com/spf13/viper

Learn more and contribute on [GitHub](https://github.com/gohugoio).



================================================
FILE: themes/hermit/exampleSite/content/posts/creating-a-new-theme.md
================================================
---
author: "Michael Henderson"
date: 2014-09-28
title: Creating a New Theme
---

## Introduction

This tutorial will show you how to create a simple theme in Hugo. I assume that you are familiar with HTML, the bash command line, and that you are comfortable using Markdown to format content. I'll explain how Hugo uses templates and how you can organize your templates to create a theme. I won't cover using CSS to style your theme.

We'll start with creating a new site with a very basic template. Then we'll add in a few pages and posts. With small variations on that, you will be able to create many different types of web sites.

In this tutorial, commands that you enter will start with the "$" prompt. The output will follow. Lines that start with "#" are comments that I've added to explain a point. When I show updates to a file, the ":wq" on the last line means to save the file.

Here's an example:

```
## this is a comment
$ echo this is a command
this is a command

## edit the file
$ vi foo.md
+++
date = "2014-09-28"
title = "creating a new theme"
+++

bah and humbug
:wq

## show it
$ cat foo.md
+++
date = "2014-09-28"
title = "creating a new theme"
+++

bah and humbug
$
```


## Some Definitions

There are a few concepts that you need to understand before creating a theme.

### Skins

Skins are the files responsible for the look and feel of your site. It’s the CSS that controls colors and fonts, it’s the Javascript that determines actions and reactions. It’s also the rules that Hugo uses to transform your content into the HTML that the site will serve to visitors.

You have two ways to create a skin. The simplest way is to create it in the ```layouts/``` directory. If you do, then you don’t have to worry about configuring Hugo to recognize it. The first place that Hugo will look for rules and files is in the ```layouts/``` directory so it will always find the skin.

Your second choice is to create it in a sub-directory of the ```themes/``` directory. If you do, then you must always tell Hugo where to search for the skin. It’s extra work, though, so why bother with it?

The difference between creating a skin in ```layouts/``` and creating it in ```themes/``` is very subtle. A skin in ```layouts/``` can’t be customized without updating the templates and static files that it is built from. A skin created in ```themes/```, on the other hand, can be and that makes it easier for other people to use it.

The rest of this tutorial will call a skin created in the ```themes/``` directory a theme.

Note that you can use this tutorial to create a skin in the ```layouts/``` directory if you wish to. The main difference will be that you won’t need to update the site’s configuration file to use a theme.

### The Home Page

The home page, or landing page, is the first page that many visitors to a site see. It is the index.html file in the root directory of the web site. Since Hugo writes files to the public/ directory, our home page is public/index.html.

### Site Configuration File

When Hugo runs, it looks for a configuration file that contains settings that override default values for the entire site. The file can use TOML, YAML, or JSON. I prefer to use TOML for my configuration files. If you prefer to use JSON or YAML, you’ll need to translate my examples. You’ll also need to change the name of the file since Hugo uses the extension to determine how to process it.

Hugo translates Markdown files into HTML. By default, Hugo expects to find Markdown files in your ```content/``` directory and template files in your ```themes/``` directory. It will create HTML files in your ```public/``` directory. You can change this by specifying alternate locations in the configuration file.

### Content

Content is stored in text files that contain two sections. The first section is the “front matter,” which is the meta-information on the content. The second section contains Markdown that will be converted to HTML.

#### Front Matter

The front matter is information about the content. Like the configuration file, it can be written in TOML, YAML, or JSON. Unlike the configuration file, Hugo doesn’t use the file’s extension to know the format. It looks for markers to signal the type. TOML is surrounded by “`+++`”, YAML by “`---`”, and JSON is enclosed in curly braces. I prefer to use TOML, so you’ll need to translate my examples if you prefer YAML or JSON.

The information in the front matter is passed into the template before the content is rendered into HTML.

#### Markdown

Content is written in Markdown which makes it easier to create the content. Hugo runs the content through a Markdown engine to create the HTML which will be written to the output file.

### Template Files

Hugo uses template files to render content into HTML. Template files are a bridge between the content and presentation. Rules in the template define what content is published, where it's published to, and how it will rendered to the HTML file. The template guides the presentation by specifying the style to use.

There are three types of templates: single, list, and partial. Each type takes a bit of content as input and transforms it based on the commands in the template.

Hugo uses its knowledge of the content to find the template file used to render the content. If it can’t find a template that is an exact match for the content, it will shift up a level and search from there. It will continue to do so until it finds a matching template or runs out of templates to try. If it can’t find a template, it will use the default template for the site.

Please note that you can use the front matter to influence Hugo’s choice of templates.

#### Single Template

A single template is used to render a single piece of content. For example, an article or post would be a single piece of content and use a single template.

#### List Template

A list template renders a group of related content. That could be a summary of recent postings or all articles in a category. List templates can contain multiple groups.

The homepage template is a special type of list template. Hugo assumes that the home page of your site will act as the portal for the rest of the content in the site.

#### Partial Template

A partial template is a template that can be included in other templates. Partial templates must be called using the “partial” template command. They are very handy for rolling up common behavior. For example, your site may have a banner that all pages use. Instead of copying the text of the banner into every single and list template, you could create a partial with the banner in it. That way if you decide to change the banner, you only have to change the partial template.

## Create a New Site

Let's use Hugo to create a new web site. I'm a Mac user, so I'll create mine in my home directory, in the Sites folder. If you're using Linux, you might have to create the folder first.

The "new site" command will create a skeleton of a site. It will give you the basic directory structure and a useable configuration file.

```
$ hugo new site ~/Sites/zafta
$ cd ~/Sites/zafta
$ ls -l
total 8
drwxr-xr-x  7 quoha  staff  238 Sep 29 16:49 .
drwxr-xr-x  3 quoha  staff  102 Sep 29 16:49 ..
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
$
```

Take a look in the content/ directory to confirm that it is empty.

The other directories (archetypes/, layouts/, and static/) are used when customizing a theme. That's a topic for a different tutorial, so please ignore them for now.

### Generate the HTML For the New Site

Running the `hugo` command with no options will read all the available content and generate the HTML files. It will also copy all static files (that's everything that's not content). Since we have an empty site, it won't do much, but it will do it very quickly.

```
$ hugo --verbose
INFO: 2014/09/29 Using config file: config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]
WARN: 2014/09/29 Unable to locate layout: [404.html]
0 draft content 
0 future content 
0 pages created 
0 tags created
0 categories created
in 2 ms
$ 
```

The "`--verbose`" flag gives extra information that will be helpful when we build the template. Every line of the output that starts with "INFO:" or "WARN:" is present because we used that flag. The lines that start with "WARN:" are warning messages. We'll go over them later.

We can verify that the command worked by looking at the directory again.

```
$ ls -l
total 8
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:02 public
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
$
```

See that new public/ directory? Hugo placed all generated content there. When you're ready to publish your web site, that's the place to start. For now, though, let's just confirm that we have what we'd expect from a site with no content.

```
$ ls -l public
total 16
-rw-r--r--  1 quoha  staff  416 Sep 29 17:02 index.xml
-rw-r--r--  1 quoha  staff  262 Sep 29 17:02 sitemap.xml
$ 
```

Hugo created two XML files, which is standard, but there are no HTML files.



### Test the New Site

Verify that you can run the built-in web server. It will dramatically shorten your development cycle if you do. Start it by running the "server" command. If it is successful, you will see output similar to the following:

```
$ hugo server --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]
WARN: 2014/09/29 Unable to locate layout: [404.html]
0 draft content 
0 future content 
0 pages created 
0 tags created
0 categories created
in 2 ms
Serving pages from /Users/quoha/Sites/zafta/public
Web Server is available at http://localhost:1313
Press Ctrl+C to stop
```

Connect to the listed URL (it's on the line that starts with "Web Server"). If everything is working correctly, you should get a page that shows the following:

```
index.xml
sitemap.xml
```

That's a listing of your public/ directory. Hugo didn't create a home page because our site has no content. When there's no index.html file in a directory, the server lists the files in the directory, which is what you should see in your browser.

Let’s go back and look at those warnings again.

```
WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]
WARN: 2014/09/29 Unable to locate layout: [404.html]
```

That second warning is easier to explain. We haven’t created a template to be used to generate “page not found errors.” The 404 message is a topic for a separate tutorial.

Now for the first warning. It is for the home page. You can tell because the first layout that it looked for was “index.html.” That’s only used by the home page.

I like that the verbose flag causes Hugo to list the files that it's searching for. For the home page, they are index.html, _default/list.html, and _default/single.html. There are some rules that we'll cover later that explain the names and paths. For now, just remember that Hugo couldn't find a template for the home page and it told you so.

At this point, you've got a working installation and site that we can build upon. All that’s left is to add some content and a theme to display it.

## Create a New Theme

Hugo doesn't ship with a default theme. There are a few available (I counted a dozen when I first installed Hugo) and Hugo comes with a command to create new themes.

We're going to create a new theme called "zafta." Since the goal of this tutorial is to show you how to fill out the files to pull in your content, the theme will not contain any CSS. In other words, ugly but functional.

All themes have opinions on content and layout. For example, Zafta uses "post" over "blog". Strong opinions make for simpler templates but differing opinions make it tougher to use themes. When you build a theme, consider using the terms that other themes do.


### Create a Skeleton

Use the hugo "new" command to create the skeleton of a theme. This creates the directory structure and places empty files for you to fill out.

```
$ hugo new theme zafta

$ ls -l
total 8
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 archetypes
-rw-r--r--  1 quoha  staff   82 Sep 29 16:49 config.toml
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 content
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:02 public
drwxr-xr-x  2 quoha  staff   68 Sep 29 16:49 static
drwxr-xr-x  3 quoha  staff  102 Sep 29 17:31 themes

$ find themes -type f | xargs ls -l
-rw-r--r--  1 quoha  staff  1081 Sep 29 17:31 themes/zafta/LICENSE.md
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/archetypes/default.md
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/_default/list.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/_default/single.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/index.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/partials/footer.html
-rw-r--r--  1 quoha  staff     0 Sep 29 17:31 themes/zafta/layouts/partials/header.html
-rw-r--r--  1 quoha  staff    93 Sep 29 17:31 themes/zafta/theme.toml
$ 
```

The skeleton includes templates (the files ending in .html), license file, a description of your theme (the theme.toml file), and an empty archetype.

Please take a minute to fill out the theme.toml and LICENSE.md files. They're optional, but if you're going to be distributing your theme, it tells the world who to praise (or blame). It's also nice to declare the license so that people will know how they can use the theme.

```
$ vi themes/zafta/theme.toml
author = "michael d henderson"
description = "a minimal working template"
license = "MIT"
name = "zafta"
source_repo = ""
tags = ["tags", "categories"]
:wq

## also edit themes/zafta/LICENSE.md and change
## the bit that says "YOUR_NAME_HERE"
```

Note that the the skeleton's template files are empty. Don't worry, we'll be changing that shortly.

```
$ find themes/zafta -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/_default/list.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/_default/single.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/index.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/partials/footer.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/partials/header.html
$
```



### Update the Configuration File to Use the Theme

Now that we've got a theme to work with, it's a good idea to add the theme name to the configuration file. This is optional, because you can always add "-t zafta" on all your commands. I like to put it the configuration file because I like shorter command lines. If you don't put it in the configuration file or specify it on the command line, you won't use the template that you're expecting to.

Edit the file to add the theme, add a title for the site, and specify that all of our content will use the TOML format.

```
$ vi config.toml
theme = "zafta"
baseurl = ""
languageCode = "en-us"
title = "zafta - totally refreshing"
MetaDataFormat = "toml"
:wq

$
```

### Generate the Site

Now that we have an empty theme, let's generate the site again.

```
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
0 pages created 
0 tags created
0 categories created
in 2 ms
$
```

Did you notice that the output is different? The warning message for the home page has disappeared and we have an additional information line saying that Hugo is syncing from the theme's directory.

Let's check the public/ directory to see what Hugo's created.

```
$ ls -l public
total 16
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:56 css
-rw-r--r--  1 quoha  staff    0 Sep 29 17:56 index.html
-rw-r--r--  1 quoha  staff  407 Sep 29 17:56 index.xml
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:56 js
-rw-r--r--  1 quoha  staff  243 Sep 29 17:56 sitemap.xml
$
```

Notice four things:

1. Hugo created a home page. This is the file public/index.html.
2. Hugo created a css/ directory.
3. Hugo created a js/ directory.
4. Hugo claimed that it created 0 pages. It created a file and copied over static files, but didn't create any pages. That's because it considers a "page" to be a file created directly from a content file. It doesn't count things like the index.html files that it creates automatically.

#### The Home Page

Hugo supports many different types of templates. The home page is special because it gets its own type of template and its own template file. The file, layouts/index.html, is used to generate the HTML for the home page. The Hugo documentation says that this is the only required template, but that depends. Hugo's warning message shows that it looks for three different templates:

```
WARN: 2014/09/29 Unable to locate layout: [index.html _default/list.html _default/single.html]
```

If it can't find any of these, it completely skips creating the home page. We noticed that when we built the site without having a theme installed.

When Hugo created our theme, it created an empty home page template. Now, when we build the site, Hugo finds the template and uses it to generate the HTML for the home page. Since the template file is empty, the HTML file is empty, too. If the template had any rules in it, then Hugo would have used them to generate the home page.

```
$ find . -name index.html | xargs ls -l
-rw-r--r--  1 quoha  staff  0 Sep 29 20:21 ./public/index.html
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 ./themes/zafta/layouts/index.html
$ 
```

#### The Magic of Static

Hugo does two things when generating the site. It uses templates to transform content into HTML and it copies static files into the site. Unlike content, static files are not transformed. They are copied exactly as they are.

Hugo assumes that your site will use both CSS and JavaScript, so it creates directories in your theme to hold them. Remember opinions? Well, Hugo's opinion is that you'll store your CSS in a directory named css/ and your JavaScript in a directory named js/. If you don't like that, you can change the directory names in your theme directory or even delete them completely. Hugo's nice enough to offer its opinion, then behave nicely if you disagree.

```
$ find themes/zafta -type d | xargs ls -ld
drwxr-xr-x  7 quoha  staff  238 Sep 29 17:38 themes/zafta
drwxr-xr-x  3 quoha  staff  102 Sep 29 17:31 themes/zafta/archetypes
drwxr-xr-x  5 quoha  staff  170 Sep 29 17:31 themes/zafta/layouts
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:31 themes/zafta/layouts/_default
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:31 themes/zafta/layouts/partials
drwxr-xr-x  4 quoha  staff  136 Sep 29 17:31 themes/zafta/static
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:31 themes/zafta/static/css
drwxr-xr-x  2 quoha  staff   68 Sep 29 17:31 themes/zafta/static/js
$ 
```

## The Theme Development Cycle

When you're working on a theme, you will make changes in the theme's directory, rebuild the site, and check your changes in the browser. Hugo makes this very easy:

1. Purge the public/ directory.
2. Run the built in web server in watch mode.
3. Open your site in a browser.
4. Update the theme.
5. Glance at your browser window to see changes.
6. Return to step 4.

I’ll throw in one more opinion: never work on a theme on a live site. Always work on a copy of your site. Make changes to your theme, test them, then copy them up to your site. For added safety, use a tool like Git to keep a revision history of your content and your theme. Believe me when I say that it is too easy to lose both your mind and your changes.

Check the main Hugo site for information on using Git with Hugo.

### Purge the public/ Directory

When generating the site, Hugo will create new files and update existing ones in the ```public/``` directory. It will not delete files that are no longer used. For example, files that were created in the wrong directory or with the wrong title will remain. If you leave them, you might get confused by them later. I recommend cleaning out your site prior to generating it.

Note: If you're building on an SSD, you should ignore this. Churning on a SSD can be costly.

### Hugo's Watch Option

Hugo's "`--watch`" option will monitor the content/ and your theme directories for changes and rebuild the site automatically.

### Live Reload

Hugo's built in web server supports live reload. As pages are saved on the server, the browser is told to refresh the page. Usually, this happens faster than you can say, "Wow, that's totally amazing."

### Development Commands

Use the following commands as the basis for your workflow.

```
## purge old files. hugo will recreate the public directory.
##
$ rm -rf public
##
## run hugo in watch mode
##
$ hugo server --watch --verbose
```

Here's sample output showing Hugo detecting a change to the template for the home page. Once generated, the web browser automatically reloaded the page. I've said this before, it's amazing.


```
$ rm -rf public
$ hugo server --watch --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
0 pages created 
0 tags created
0 categories created
in 2 ms
Watching for changes in /Users/quoha/Sites/zafta/content
Serving pages from /Users/quoha/Sites/zafta/public
Web Server is available at http://localhost:1313
Press Ctrl+C to stop
INFO: 2014/09/29 File System Event: ["/Users/quoha/Sites/zafta/themes/zafta/layouts/index.html": MODIFY|ATTRIB]
Change detected, rebuilding site

WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
0 pages created 
0 tags created
0 categories created
in 1 ms
```

## Update the Home Page Template

The home page is one of a few special pages that Hugo creates automatically. As mentioned earlier, it looks for one of three files in the theme's layout/ directory:

1. index.html
2. _default/list.html
3. _default/single.html

We could update one of the default templates, but a good design decision is to update the most specific template available. That's not a hard and fast rule (in fact, we'll break it a few times in this tutorial), but it is a good generalization.

### Make a Static Home Page

Right now, that page is empty because we don't have any content and we don't have any logic in the template. Let's change that by adding some text to the template.

```
$ vi themes/zafta/layouts/index.html
<!DOCTYPE html> 
<html> 
<body> 
  <p>hugo says hello!</p> 
</body> 
</html> 
:wq

$
```

Build the web site and then verify the results.

```
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
0 pages created 
0 tags created
0 categories created
in 2 ms

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  78 Sep 29 21:26 public/index.html

$ cat public/index.html 
<!DOCTYPE html> 
<html> 
<body> 
  <p>hugo says hello!</p> 
</html>
```

#### Live Reload

Note: If you're running the server with the `--watch` option, you'll see different content in the file:

```
$ cat public/index.html 
<!DOCTYPE html> 
<html> 
<body> 
  <p>hugo says hello!</p> 
<script>document.write('<script src="http://' 
        + (location.host || 'localhost').split(':')[0] 
    + ':1313/livereload.js?mindelay=10"></' 
        + 'script>')</script></body> 
</html>
```

When you use `--watch`, the Live Reload script is added by Hugo. Look for live reload in the documentation to see what it does and how to disable it.

### Build a "Dynamic" Home Page

"Dynamic home page?" Hugo's a static web site generator, so this seems an odd thing to say. I mean let's have the home page automatically reflect the content in the site every time Hugo builds it. We'll use iteration in the template to do that.

#### Create New Posts

Now that we have the home page generating static content, let's add some content to the site. We'll display these posts as a list on the home page and on their own page, too.

Hugo has a command to generate a skeleton post, just like it does for sites and themes.

```
$ hugo --verbose new post/first.md
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 attempting to create  post/first.md of post
INFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/default.md
ERROR: 2014/09/29 Unable to Cast <nil> to map[string]interface{}

$ 
```

That wasn't very nice, was it?

The "new" command uses an archetype to create the post file. Hugo created an empty default archetype file, but that causes an error when there's a theme. For me, the workaround was to create an archetypes file specifically for the post type.

```
$ vi themes/zafta/archetypes/post.md
+++
Description = ""
Tags = []
Categories = []
+++
:wq

$ find themes/zafta/archetypes -type f | xargs ls -l
-rw-r--r--  1 quoha  staff   0 Sep 29 21:53 themes/zafta/archetypes/default.md
-rw-r--r--  1 quoha  staff  51 Sep 29 21:54 themes/zafta/archetypes/post.md

$ hugo --verbose new post/first.md
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 attempting to create  post/first.md of post
INFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/post.md
INFO: 2014/09/29 creating /Users/quoha/Sites/zafta/content/post/first.md
/Users/quoha/Sites/zafta/content/post/first.md created

$ hugo --verbose new post/second.md
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 attempting to create  post/second.md of post
INFO: 2014/09/29 curpath: /Users/quoha/Sites/zafta/themes/zafta/archetypes/post.md
INFO: 2014/09/29 creating /Users/quoha/Sites/zafta/content/post/second.md
/Users/quoha/Sites/zafta/content/post/second.md created

$ ls -l content/post
total 16
-rw-r--r--  1 quoha  staff  104 Sep 29 21:54 first.md
-rw-r--r--  1 quoha  staff  105 Sep 29 21:57 second.md

$ cat content/post/first.md 
+++
Categories = []
Description = ""
Tags = []
date = "2014-09-29T21:54:53-05:00"
title = "first"

+++
my first post

$ cat content/post/second.md 
+++
Categories = []
Description = ""
Tags = []
date = "2014-09-29T21:57:09-05:00"
title = "second"

+++
my second post

$ 
```

Build the web site and then verify the results.

```
$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"category":"categories", "tag":"tags"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
2 pages created 
0 tags created
0 categories created
in 4 ms
$
```

The output says that it created 2 pages. Those are our new posts:

```
$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  78 Sep 29 22:13 public/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:13 public/post/first/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:13 public/post/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:13 public/post/second/index.html
$
```

The new files are empty because because the templates used to generate the content are empty. The homepage doesn't show the new content, either. We have to update the templates to add the posts.

### List and Single Templates

In Hugo, we have three major kinds of templates. There's the home page template that we updated previously. It is used only by the home page. We also have "single" templates which are used to generate output for a single content file. We also have "list" templates that are used to group multiple pieces of content before generating output.

Generally speaking, list templates are named "list.html" and single templates are named "single.html."

There are three other types of templates: partials, content views, and terms. We will not go into much detail on these.

### Add Content to the Homepage

The home page will contain a list of posts. Let's update its template to add the posts that we just created. The logic in the template will run every time we build the site.

```
$ vi themes/zafta/layouts/index.html 
<!DOCTYPE html>
<html>
<body>
  {{ range first 10 .Data.Pages }}
    <h1>{{ .Title }}</h1>
  {{ end }}
</body>
</html>
:wq

$
```

Hugo uses the Go template engine. That engine scans the template files for commands which are enclosed between "{{" and "}}". In our template, the commands are:

1. range
2. .Title
3. end

The "range" command is an iterator. We're going to use it to go through the first ten pages. Every HTML file that Hugo creates is treated as a page, so looping through the list of pages will look at every file that will be created.

The ".Title" command prints the value of the "title" variable. Hugo pulls it from the front matter in the Markdown file.

The "end" command signals the end of the range iterator. The engine loops back to the top of the iteration when it finds "end." Everything between the "range" and "end" is evaluated every time the engine goes through the iteration. In this file, that would cause the title from the first ten pages to be output as heading level one.

It's helpful to remember that some variables, like .Data, are created before any output files. Hugo loads every content file into the variable and then gives the template a chance to process before creating the HTML files.

Build the web site and then verify the results.

```
$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"tag":"tags", "category":"categories"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
2 pages created 
0 tags created
0 categories created
in 4 ms
$ find public -type f -name '*.html' | xargs ls -l 
-rw-r--r--  1 quoha  staff  94 Sep 29 22:23 public/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:23 public/post/first/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:23 public/post/index.html
-rw-r--r--  1 quoha  staff   0 Sep 29 22:23 public/post/second/index.html
$ cat public/index.html 
<!DOCTYPE html>
<html>
<body>
  
    <h1>second</h1>
  
    <h1>first</h1>
  
</body>
</html>
$
```

Congratulations, the home page shows the title of the two posts. The posts themselves are still empty, but let's take a moment to appreciate what we've done. Your template now generates output dynamically. Believe it or not, by inserting the range command inside of those curly braces, you've learned everything you need to know to build a theme. All that's really left is understanding which template will be used to generate each content file and becoming familiar with the commands for the template engine.

And, if that were entirely true, this tutorial would be much shorter. There are a few things to know that will make creating a new template much easier. Don't worry, though, that's all to come.

### Add Content to the Posts

We're working with posts, which are in the content/post/ directory. That means that their section is "post" (and if we don't do something weird, their type is also "post").

Hugo uses the section and type to find the template file for every piece of content. Hugo will first look for a template file that matches the section or type name. If it can't find one, then it will look in the _default/ directory. There are some twists that we'll cover when we get to categories and tags, but for now we can assume that Hugo will try post/single.html, then _default/single.html.

Now that we know the search rule, let's see what we actually have available:

```
$ find themes/zafta -name single.html | xargs ls -l
-rw-r--r--  1 quoha  staff  132 Sep 29 17:31 themes/zafta/layouts/_default/single.html
```

We could create a new template, post/single.html, or change the default. Since we don't know of any other content types, let's start with updating the default.

Remember, any content that we haven't created a template for will end up using this template. That can be good or bad. Bad because I know that we're going to be adding different types of content and we're going to end up undoing some of the changes we've made. It's good because we'll be able to see immediate results. It's also good to start here because we can start to build the basic layout for the site. As we add more content types, we'll refactor this file and move logic around. Hugo makes that fairly painless, so we'll accept the cost and proceed.

Please see the Hugo documentation on template rendering for all the details on determining which template to use. And, as the docs mention, if you're building a single page application (SPA) web site, you can delete all of the other templates and work with just the default single page. That's a refreshing amount of joy right there.

#### Update the Template File

```
$ vi themes/zafta/layouts/_default/single.html 
<!DOCTYPE html>
<html>
<head>
  <title>{{ .Title }}</title>
</head>
<body>
  <h1>{{ .Title }}</h1>
  {{ .Content }}
</body>
</html>
:wq

$
```

Build the web site and verify the results.

```
$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"tag":"tags", "category":"categories"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
2 pages created 
0 tags created
0 categories created
in 4 ms

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff   94 Sep 29 22:40 public/index.html
-rw-r--r--  1 quoha  staff  125 Sep 29 22:40 public/post/first/index.html
-rw-r--r--  1 quoha  staff    0 Sep 29 22:40 public/post/index.html
-rw-r--r--  1 quoha  staff  128 Sep 29 22:40 public/post/second/index.html

$ cat public/post/first/index.html 
<!DOCTYPE html>
<html>
<head>
  <title>first</title>
</head>
<body>
  <h1>first</h1>
  <p>my first post</p>

</body>
</html>

$ cat public/post/second/index.html 
<!DOCTYPE html>
<html>
<head>
  <title>second</title>
</head>
<body>
  <h1>second</h1>
  <p>my second post</p>

</body>
</html>
$
```

Notice that the posts now have content. You can go to localhost:1313/post/first to verify.

### Linking to Content

The posts are on the home page. Let's add a link from there to the post. Since this is the home page, we'll update its template.

```
$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  {{ range first 10 .Data.Pages }}
    <h1><a href="{{ .Permalink }}">{{ .Title }}</a></h1>
  {{ end }}
</body>
</html>
```

Build the web site and verify the results.

```
$ rm -rf public
$ hugo --verbose
INFO: 2014/09/29 Using config file: /Users/quoha/Sites/zafta/config.toml
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/themes/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 syncing from /Users/quoha/Sites/zafta/static/ to /Users/quoha/Sites/zafta/public/
INFO: 2014/09/29 found taxonomies: map[string]string{"tag":"tags", "category":"categories"}
WARN: 2014/09/29 Unable to locate layout: [404.html theme/404.html]
0 draft content 
0 future content 
2 pages created 
0 tags created
0 categories created
in 4 ms

$ find public -type f -name '*.html' | xargs ls -l
-rw-r--r--  1 quoha  staff  149 Sep 29 22:44 public/index.html
-rw-r--r--  1 quoha  staff  125 Sep 29 22:44 public/post/first/index.html
-rw-r--r--  1 quoha  staff    0 Sep 29 22:44 public/post/index.html
-rw-r--r--  1 quoha  staff  128 Sep 29 22:44 public/post/second/index.html

$ cat public/index.html 
<!DOCTYPE html>
<html>
<body>
  
    <h1><a href="/post/second/">second</a></h1>
  
    <h1><a href="/post/first/">first</a></h1>
  
</body>
</html>

$
```

### Create a Post Listing

We have the posts displaying on the home page and on their own page. We also have a file public/post/index.html that is empty. Let's make it show a list of all posts (not just the first ten).

We need to decide which template to update. This will be a listing, so it should be a list template. Let's take a quick look and see which list templates are available.

```
$ find themes/zafta -name list.html | xargs ls -l
-rw-r--r--  1 quoha  staff  0 Sep 29 17:31 themes/zafta/layouts/_default/list.html
```

As with the single post, we have to decide to update _default/list.html or create post/list.html. We still don't have multiple content types, so let's stay consistent and update the default list template.

## Creating Top Level Pages

Let's add an "about" page and display it at the top level (as opposed to a sub-level like we did with posts).

The default in Hugo is to use the directory structure of the content/ directory to guide the location of the generated html in the public/ directory. Let's verify that by creating an "about" page at the top level:

```
$ vi content/about.md 
+++
title = "about"
description = "about this site"
date = "2014-09-27"
slug = "about time"
+++

## about us

i'm speechless
:wq
```

Generate the web site and verify the results.

```
$ find public -name '*.html' | xargs ls -l
-rw-rw-r--  1 mdhender  staff   334 Sep 27 15:08 public/about-time/index.html
-rw-rw-r--  1 mdhender  staff   527 Sep 27 15:08 public/index.html
-rw-rw-r--  1 mdhender  staff   358 Sep 27 15:08 public/post/first-post/index.html
-rw-rw-r--  1 mdhender  staff     0 Sep 27 15:08 public/post/index.html
-rw-rw-r--  1 mdhender  staff   342 Sep 27 15:08 public/post/second-post/index.html
```

Notice that the page wasn't created at the top level. It was created in a sub-directory named 'about-time/'. That name came from our slug. Hugo will use the slug to name the generated content. It's a reasonable default, by the way, but we can learn a few things by fighting it for this file.

One other thing. Take a look at the home page.

```
$ cat public/index.html
<!DOCTYPE html>
<html>
<body>
    <h1><a href="http://localhost:1313/post/theme/">creating a new theme</a></h1>
    <h1><a href="http://localhost:1313/about-time/">about</a></h1>
    <h1><a href="http://localhost:1313/post/second-post/">second</a></h1>
    <h1><a href="http://localhost:1313/post/first-post/">first</a></h1>
<script>document.write('<script src="http://'
        + (location.host || 'localhost').split(':')[0]
		+ ':1313/livereload.js?mindelay=10"></'
        + 'script>')</script></body>
</html>
```

Notice that the "about" link is listed with the posts? That's not desirable, so let's change that first.

```
$ vi themes/zafta/layouts/index.html
<!DOCTYPE html>
<html>
<body>
  <h1>posts</h1>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "post"}}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}

  <h1>pages</h1>
  {{ range .Data.Pages }}
    {{ if eq .Type "page" }}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}
</body>
</html>
:wq
```

Generate the web site and verify the results. The home page has two sections, posts and pages, and each section has the right set of headings and links in it.

But, that about page still renders to about-time/index.html.

```
$ find public -name '*.html' | xargs ls -l
-rw-rw-r--  1 mdhender  staff    334 Sep 27 15:33 public/about-time/index.html
-rw-rw-r--  1 mdhender  staff    645 Sep 27 15:33 public/index.html
-rw-rw-r--  1 mdhender  staff    358 Sep 27 15:33 public/post/first-post/index.html
-rw-rw-r--  1 mdhender  staff      0 Sep 27 15:33 public/post/index.html
-rw-rw-r--  1 mdhender  staff    342 Sep 27 15:33 public/post/second-post/index.html
```

Knowing that hugo is using the slug to generate the file name, the simplest solution is to change the slug. Let's do it the hard way and change the permalink in the configuration file.

```
$ vi config.toml
[permalinks]
	page = "/:title/"
	about = "/:filename/"
```

Generate the web site and verify that this didn't work. Hugo lets "slug" or "URL" override the permalinks setting in the configuration file. Go ahead and comment out the slug in content/about.md, then generate the web site to get it to be created in the right place.

## Sharing Templates

If you've been following along, you probably noticed that posts have titles in the browser and the home page doesn't. That's because we didn't put the title in the home page's template (layouts/index.html). That's an easy thing to do, but let's look at a different option.

We can put the common bits into a shared template that's stored in the themes/zafta/layouts/partials/ directory.

### Create the Header and Footer Partials

In Hugo, a partial is a sugar-coated template. Normally a template reference has a path specified. Partials are different. Hugo searches for them along a TODO defined search path. This makes it easier for end-users to override the theme's presentation.

```
$ vi themes/zafta/layouts/partials/header.html
<!DOCTYPE html>
<html>
<head>
	<title>{{ .Title }}</title>
</head>
<body>
:wq

$ vi themes/zafta/layouts/partials/footer.html
</body>
</html>
:wq
```

### Update the Home Page Template to Use the Partials

The most noticeable difference between a template call and a partials call is the lack of path:

```
{{ template "theme/partials/header.html" . }}
```
versus
```
{{ partial "header.html" . }}
```
Both pass in the context.

Let's change the home page template to use these new partials.

```
$ vi themes/zafta/layouts/index.html
{{ partial "header.html" . }}

  <h1>posts</h1>
  {{ range first 10 .Data.Pages }}
    {{ if eq .Type "post"}}
      <h2><a href="{{ .Permalink }}">{{ .Title }}</a></h2>
    {{ end }}
  {{ end }}

  <h1>pages</h1>
  {{ range .Data.Pages }}
    {{ if or (eq .Type "page") (eq .Type "about") }}
      <h2><a href="{{ .Permalink }}">{{ .Type }} - {{ .Title }} - {{ .RelPermalink }}</a></h2>
    {{ end }}
  {{ end }}

{{ partial "footer.html" . }}
:wq
```

Generate the web site and verify the results. The title on the home page is now "your title here", which comes from the "title" variable in the config.toml file.

### Update the Default Single Template to Use the Partials

```
$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq
```

Generate the web site and verify the results. The title on the posts and the about page should both reflect the value in the markdown file.

## Add “Date Published” to Posts

It's common to have posts display the date that they were written or published, so let's add that. The front matter of our posts has a variable named "date." It's usually the date the content was created, but let's pretend that's the value we want to display.

### Add “Date Published” to the Template

We'll start by updating the template used to render the posts. The template code will look like:

```
{{ .Date.Format "Mon, Jan 2, 2006" }}
```

Posts use the default single template, so we'll change that file.

```
$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  <h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq
```

Generate the web site and verify the results. The posts now have the date displayed in them. There's a problem, though. The "about" page also has the date displayed.

As usual, there are a couple of ways to make the date display only on posts. We could do an "if" statement like we did on the home page. Another way would be to create a separate template for posts.

The "if" solution works for sites that have just a couple of content types. It aligns with the principle of "code for today," too.

Let's assume, though, that we've made our site so complex that we feel we have to create a new template type. In Hugo-speak, we're going to create a section template.

Let's restore the default single template before we forget.

```
$ mkdir themes/zafta/layouts/post
$ vi themes/zafta/layouts/_default/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq
```

Now we'll update the post's version of the single template. If you remember Hugo's rules, the template engine will use this version over the default.

```
$ vi themes/zafta/layouts/post/single.html
{{ partial "header.html" . }}

  <h1>{{ .Title }}</h1>
  <h2>{{ .Date.Format "Mon, Jan 2, 2006" }}</h2>
  {{ .Content }}

{{ partial "footer.html" . }}
:wq

```

Note that we removed the date logic from the default template and put it in the post template. Generate the web site and verify the results. Posts have dates and the about page doesn't.

### Don't Repeat Yourself

DRY is a good design goal and Hugo does a great job supporting it. Part of the art of a good template is knowing when to add a new template and when to update an existing one. While you're figuring that out, accept that you'll be doing some refactoring. Hugo makes that easy and fast, so it's okay to delay splitting up a template.


================================================
FILE: themes/hermit/exampleSite/content/posts/goisforlovers.md
================================================
+++
title = "(Hu)go Template Primer"
tags = [
    "go",
    "golang",
    "templates",
    "themes",
    "development",
]
date = "2014-04-02"
toc = true
+++

Hugo uses the excellent [Go][] [html/template][gohtmltemplate] library for
its template engine. It is an extremely lightweight engine that provides a very
small amount of logic. In our experience that it is just the right amount of
logic to be able to create a good static website. If you have used other
template systems from different languages or frameworks you will find a lot of
similarities in Go templates.

This document is a brief primer on using Go templates. The [Go docs][gohtmltemplate]
provide more details.

## Introduction to Go Templates

Go templates provide an extremely simple template language. It adheres to the
belief that only the most basic of logic belongs in the template or view layer.
One consequence of this simplicity is that Go templates parse very quickly.

A unique characteristic of Go templates is they are content aware. Variables and
content will be sanitized depending on the context of where they are used. More
details can be found in the [Go docs][gohtmltemplate].

## Basic Syntax

Golang templates are HTML files with the addition of variables and
functions.

**Go variables and functions are accessible within {{ }}**

Accessing a predefined variable "foo":

    {{ foo }}

**Parameters are separated using spaces**

Calling the add function with input of 1, 2:

    {{ add 1 2 }}

**Methods and fields are accessed via dot notation**

Accessing the Page Parameter "bar"

    {{ .Params.bar }}

**Parentheses can be used to group items together**

    {{ if or (isset .Params "alt") (isset .Params "caption") }} Caption {{ end }}


## Variables

Each Go template has a struct (object) made available to it. In hugo each
template is passed either a page or a node struct depending on which type of
page you are rendering. More details are available on the
[variables](/layout/variables) page.

A variable is accessed by referencing the variable name.

    <title>{{ .Title }}</title>

Variables can also be defined and referenced.

    {{ $address := "123 Main St."}}
    {{ $address }}


## Functions

Go template ship with a few functions which provide basic functionality. The Go
template system also provides a mechanism for applications to extend the
available functions with their own. [Hugo template
functions](/layout/functions) provide some additional functionality we believe
are useful for building websites. Functions are called by using their name
followed by the required parameters separated by spaces. Template
functions cannot be added without recompiling hugo.

**Example:**

    {{ add 1 2 }}

## Includes

When including another template you will pass to it the data it will be
able to access. To pass along the current context please remember to
include a trailing dot. The templates location will always be starting at
the /layout/ directory within Hugo.

**Example:**

    {{ template "chrome/header.html" . }}


## Logic

Go templates provide the most basic iteration and conditional logic.

### Iteration

Just like in Go, the Go templates make heavy use of range to iterate over
a map, array or slice. The following are different examples of how to use
range.

**Example 1: Using Context**

    {{ range array }}
        {{ . }}
    {{ end }}

**Example 2: Declaring value variable name**

    {{range $element := array}}
        {{ $element }}
    {{ end }}

**Example 2: Declaring key and value variable name**

    {{range $index, $element := array}}
        {{ $index }}
        {{ $element }}
    {{ end }}

### Conditionals

If, else, with, or, & and provide the framework for handling conditional
logic in Go Templates. Like range, each statement is closed with `end`.


Go Templates treat the following values as false:

* false
* 0
* any array, slice, map, or string of length zero

**Example 1: If**

    {{ if isset .Params "title" }}<h4>{{ index .Params "title" }}</h4>{{ end }}

**Example 2: If -> Else**

    {{ if isset .Params "alt" }}
        {{ index .Params "alt" }}
    {{else}}
        {{ index .Params "caption" }}
    {{ end }}

**Example 3: And & Or**

    {{ if and (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}

**Example 4: With**

An alternative way of writing "if" and then referencing the same value
is to use "with" instead. With rebinds the context `.` within its scope,
and skips the block if the variable is absent.

The first example above could be simplified as:

    {{ with .Params.title }}<h4>{{ . }}</h4>{{ end }}

**Example 5: If -> Else If**

    {{ if isset .Params "alt" }}
        {{ index .Params "alt" }}
    {{ else if isset .Params "caption" }}
        {{ index .Params "caption" }}
    {{ end }}

## Pipes

One of the most powerful components of Go templates is the ability to
stack actions one after another. This is done by using pipes. Borrowed
from unix pipes, the concept is simple, each pipeline's output becomes the
input of the following pipe.

Because of the very simple syntax of Go templates, the pipe is essential
to being able to chain together function calls. One limitation of the
pipes is that they only can work with a single value and that value
becomes the last parameter of the next pipeline.

A few simple examples should help convey how to use the pipe.

**Example 1 :**

    {{ if eq 1 1 }} Same {{ end }}

is the same as

    {{ eq 1 1 | if }} Same {{ end }}

It does look odd to place the if at the end, but it does provide a good
illustration of how to use the pipes.

**Example 2 :**

    {{ index .Params "disqus_url" | html }}

Access the page parameter called "disqus_url" and escape the HTML.

**Example 3 :**

    {{ if or (or (isset .Params "title") (isset .Params "caption")) (isset .Params "attr")}}
    Stuff Here
    {{ end }}

Could be rewritten as

    {{  isset .Params "caption" | or isset .Params "title" | or isset .Params "attr" | if }}
    Stuff Here
    {{ end }}


## Context (aka. the dot)

The most easily overlooked concept to understand about Go templates is that {{ . }}
always refers to the current context. In the top level of your template this
will be the data set made available to it. Inside of a iteration it will have
the value of the current item. When inside of a loop the context has changed. .
will no longer refer to the data available to the entire page. If you need to
access this from within the loop you will likely want to set it to a variable
instead of depending on the context.

**Example:**

      {{ $title := .Site.Title }}
      {{ range .Params.tags }}
        <li> <a href="{{ $baseurl }}/tags/{{ . | urlize }}">{{ . }}</a> - {{ $title }} </li>
      {{ end }}

Notice how once we have entered the loop the value of {{ . }} has changed. We
have defined a variable outside of the loop so we have access to it from within
the loop.

# Hugo Parameters

Hugo provides the option of passing values to the template language
through the site configuration (for sitewide values), or through the meta
data of each specific piece of content. You can define any values of any
type (supported by your front matter/config format) and use them however
you want to inside of your templates.


## Using Content (page) Parameters

In each piece of content you can provide variables to be used by the
templates. This happens in the [front matter](/content/front-matter).

An example of this is used in this documentation site. Most of the pages
benefit from having the table of contents provided. Sometimes the TOC just
doesn't make a lot of sense. We've defined a variable in our front matter
of some pages to turn off the TOC from being displayed.

Here is the example front matter:

```
---
title: "Permalinks"
date: "2013-11-18"
aliases:
  - "/doc/permalinks/"
groups: ["extras"]
groups_weight: 30
notoc: true
---
```

Here is the corresponding code inside of the template:

      {{ if not .Params.notoc }}
        <div id="toc" class="well col-md-4 col-sm-6">
        {{ .TableOfContents }}
        </div>
      {{ end }}



## Using Site (config) Parameters
In your top-level configuration file (eg, `config.yaml`) you can define site
parameters, which are values which will be available to you in chrome.

For instance, you might declare:

```yaml
params:
  CopyrightHTML: "Copyright &#xA9; 2013 John Doe. All Rights Reserved."
  TwitterUser: "spf13"
  SidebarRecentLimit: 5
```

Within a footer layout, you might then declare a `<footer>` which is only
provided if the `CopyrightHTML` parameter is provided, and if it is given,
you would declare it to be HTML-safe, so that the HTML entity is not escaped
again.  This would let you easily update just your top-level config file each
January 1st, instead of hunting through your templates.

```
{{if .Site.Params.CopyrightHTML}}<footer>
<div class="text-center">{{.Site.Params.CopyrightHTML | safeHtml}}</div>
</footer>{{end}}
```

An alternative way of writing the "if" and then referencing the same value
is to use "with" instead. With rebinds the context `.` within its scope,
and skips the block if the variable is absent:

```
{{with .Site.Params.TwitterUser}}<span class="twitter">
<a href="https://twitter.com/{{.}}" rel="author">
<img src="/images/twitter.png" width="48" height="48" title="Twitter: {{.}}"
 alt="Twitter"></a>
</span>{{end}}
```

Finally, if you want to pull "magic constants" out of your layouts, you can do
so, such as in this example:

```
<nav class="recent">
  <h1>Recent Posts</h1>
  <ul>{{range first .Site.Params.SidebarRecentLimit .Site.Recent}}
    <li><a href="{{.RelPermalink}}">{{.Title}}</a></li>
  {{end}}</ul>
</nav>
```


[go]: https://golang.org/
[gohtmltemplate]: https://golang.org/pkg/html/template/


================================================
FILE: themes/hermit/exampleSite/content/posts/hugoisforlovers.md
================================================
+++
title = "Getting Started with Hugo"
tags = [
    "go",
    "golang",
    "hugo",
    "development",
]
date = "2014-04-02"
toc = true
+++

## Step 1. Install Hugo

Go to [Hugo releases](https://github.com/spf13/hugo/releases) and download the
appropriate version for your OS and architecture.

Save it somewhere specific as we will be using it in the next step.

More complete instructions are available at [Install Hugo](https://gohugo.io/getting-started/installing/)

## Step 2. Build the Docs

Hugo has its own example site which happens to also be the documentation site
you are reading right now.

Follow the following steps:

 1. Clone the [Hugo repository](http://github.com/spf13/hugo)
 2. Go into the repo
 3. Run hugo in server mode and build the docs
 4. Open your browser to http://localhost:1313

Corresponding pseudo commands:

    git clone https://github.com/spf13/hugo
    cd hugo
    /path/to/where/you/installed/hugo server --source=./docs
    > 29 pages created
    > 0 tags index created
    > in 27 ms
    > Web Server is available at http://localhost:1313
    > Press ctrl+c to stop

Once you've gotten here, follow along the rest of this page on your local build.

## Step 3. Change the docs site

Stop the Hugo process by hitting Ctrl+C.

Now we are going to run hugo again, but this time with hugo in watch mode.

    /path/to/hugo/from/step/1/hugo server --source=./docs --watch
    > 29 pages created
    > 0 tags index created
    > in 27 ms
    > Web Server is available at http://localhost:1313
    > Watching for changes in /Users/spf13/Code/hugo/docs/content
    > Press ctrl+c to stop


Open your [favorite editor](http://vim.spf13.com) and change one of the source
content pages. How about changing this very file to *fix the typo*. How about changing this very file to *fix the typo*.

Content files are found in `docs/content/`. Unless otherwise specified, files
are located at the same relative location as the url, in our case
`docs/content/overview/quickstart.md`.

Change and save this file.. Notice what happened in your terminal.

    > Change detected, rebuilding site

    > 29 pages created
    > 0 tags index created
    > in 26 ms

Refresh the browser and observe that the typo is now fixed.

Notice how quick that was. Try to refresh the site before it's finished building. I double dare you.
Having nearly instant feedback enables you to have your creativity flow without waiting for long builds.

## Step 4. Have fun

The best way to learn something is to play with it.


================================================
FILE: themes/hermit/exampleSite/content/posts/migrate-from-jekyll.md
================================================
---
date: 2014-03-10
title: Migrate to Hugo from Jekyll
toc: true
---

## Move static content to `static`
Jekyll has a rule that any directory not starting with `_` will be copied as-is to the `_site` output. Hugo keeps all static content under `static`. You should therefore move it all there.
With Jekyll, something that looked like

    ▾ <root>/
        ▾ images/
            logo.png

should become

    ▾ <root>/
        ▾ static/
            ▾ images/
                logo.png

Additionally, you'll want any files that should reside at the root (such as `CNAME`) to be moved to `static`.

## Create your Hugo configuration file
Hugo can read your configuration as JSON, YAML or TOML. Hugo supports parameters custom configuration too. Refer to the [Hugo configuration documentation](/overview/configuration/) for details.

## Set your configuration publish folder to `_site`
The default is for Jekyll to publish to `_site` and for Hugo to publish to `public`. If, like me, you have [`_site` mapped to a git submodule on the `gh-pages` branch](http://blog.blindgaenger.net/generate_github_pages_in_a_submodule.html), you'll want to do one of two alternatives:

1. Change your submodule to point to map `gh-pages` to public instead of `_site` (recommended).

        git submodule deinit _site
        git rm _site
        git submodule add -b gh-pages git@github.com:your-username/your-repo.git public

2. Or, change the Hugo configuration to use `_site` instead of `public`.

        {
            ..
            "publishdir": "_site",
            ..
        }

## Convert Jekyll templates to Hugo templates
That's the bulk of the work right here. The documentation is your friend. You should refer to [Jekyll's template documentation](http://jekyllrb.com/docs/templates/) if you need to refresh your memory on how you built your blog and [Hugo's template](/layout/templates/) to learn Hugo's way.

As a single reference data point, converting my templates for [heyitsalex.net](http://heyitsalex.net/) took me no more than a few hours.

## Convert Jekyll plugins to Hugo shortcodes
Jekyll has [plugins](http://jekyllrb.com/docs/plugins/); Hugo has [shortcodes](/doc/shortcodes/). It's fairly trivial to do a port.

### Implementation
As an example, I was using a custom [`image_tag`](https://github.com/alexandre-normand/alexandre-normand/blob/74bb12036a71334fdb7dba84e073382fc06908ec/_plugins/image_tag.rb) plugin to generate figures with caption when running Jekyll. As I read about shortcodes, I found Hugo had a nice built-in shortcode that does exactly the same thing.

Jekyll's plugin:

    module Jekyll
      class ImageTag < Liquid::Tag
        @url = nil
        @caption = nil
        @class = nil
        @link = nil
        // Patterns
        IMAGE_URL_WITH_CLASS_AND_CAPTION =
        IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK = /(\w+)(\s+)((https?:\/\/|\/)(\S+))(\s+)"(.*?)"(\s+)->((https?:\/\/|\/)(\S+))(\s*)/i
        IMAGE_URL_WITH_CAPTION = /((https?:\/\/|\/)(\S+))(\s+)"(.*?)"/i
        IMAGE_URL_WITH_CLASS = /(\w+)(\s+)((https?:\/\/|\/)(\S+))/i
        IMAGE_URL = /((https?:\/\/|\/)(\S+))/i
        def initialize(tag_name, markup, tokens)
          super
          if markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION_AND_LINK
            @class   = $1
            @url     = $3
            @caption = $7
            @link = $9
          elsif markup =~ IMAGE_URL_WITH_CLASS_AND_CAPTION
            @class   = $1
            @url     = $3
            @caption = $7
          elsif markup =~ IMAGE_URL_WITH_CAPTION
            @url     = $1
            @caption = $5
          elsif markup =~ IMAGE_URL_WITH_CLASS
            @class = $1
            @url   = $3
          elsif markup =~ IMAGE_URL
            @url = $1
          end
        end
        def render(context)
          if @class
            source = "<figure class='#{@class}'>"
          else
            source = "<figure>"
          end
          if @link
            source += "<a href=\"#{@link}\">"
          end
          source += "<img src=\"#{@url}\">"
          if @link
            source += "</a>"
          end
          source += "<figcaption>#{@caption}</figcaption>" if @caption
          source += "</figure>"
          source
        end
      end
    end
    Liquid::Template.register_tag('image', Jekyll::ImageTag)

is written as this Hugo shortcode:

    <!-- image -->
    <figure {{ with .Get "class" }}class="{{.}}"{{ end }}>
        {{ with .Get "link"}}<a href="{{.}}">{{ end }}
            <img src="{{ .Get "src" }}" {{ if or (.Get "alt") (.Get "caption") }}alt="{{ with .Get "alt"}}{{.}}{{else}}{{ .Get "caption" }}{{ end }}"{{ end }} />
        {{ if .Get "link"}}</a>{{ end }}
        {{ if or (or (.Get "title") (.Get "caption")) (.Get "attr")}}
        <figcaption>{{ if isset .Params "title" }}
            {{ .Get "title" }}{{ end }}
            {{ if or (.Get "caption") (.Get "attr")}}<p>
            {{ .Get "caption" }}
            {{ with .Get "attrlink"}}<a href="{{.}}"> {{ end }}
                {{ .Get "attr" }}
            {{ if .Get "attrlink"}}</a> {{ end }}
            </p> {{ end }}
        </figcaption>
        {{ end }}
    </figure>
    <!-- image -->

### Usage
I simply changed:

    {% image full http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg "One of my favorite touristy-type photos. I secretly waited for the good light while we were "having fun" and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." ->http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/ %}

to this (this example uses a slightly extended version named `fig`, different than the built-in `figure`):

    {{%/* fig class="full" src="http://farm5.staticflickr.com/4136/4829260124_57712e570a_o_d.jpg" title="One of my favorite touristy-type photos. I secretly waited for the good light while we were having fun and took this. Only regret: a stupid pole in the top-left corner of the frame I had to clumsily get rid of at post-processing." link="http://www.flickr.com/photos/alexnormand/4829260124/in/set-72157624547713078/" */%}}

As a bonus, the shortcode named parameters are, arguably, more readable.

## Finishing touches
### Fix content
Depending on the amount of customization that was done with each post with Jekyll, this step will require more or less effort. There are no hard and fast rules here except that `hugo server --watch` is your friend. Test your changes and fix errors as needed.

### Clean up
You'll want to remove the Jekyll configuration at this point. If you have anything else that isn't used, delete it.

## A practical example in a diff
[Hey, it's Alex](http://heyitsalex.net/) was migrated in less than a _father-with-kids day_ from Jekyll to Hugo. You can see all the changes (and screw-ups) by looking at this [diff](https://github.com/alexandre-normand/alexandre-normand/compare/869d69435bd2665c3fbf5b5c78d4c22759d7613a...b7f6605b1265e83b4b81495423294208cc74d610).


================================================
FILE: themes/hermit/exampleSite/content/posts/post-with-featured-image.md
================================================
---
title: "Post With Featured Image"
date: 2018-10-01T16:15:09+08:00
draft: false
images: 
  - https://picsum.photos/1024/768/?random
tags: 
  - Demo
  - Image
---

Just define the image URL in the content’s front matter, the featured image will be displayed as the background. 

For example:

```yaml
---
images:
  - https://picsum.photos/1024/768/?random
---
```

This is an array, you can set multiple urls, only the first url will be used. These images is also used in [Twitter Cards](https://developer.twitter.com/en/docs/tweets/optimize-with-cards/guides/getting-started.html) and the [Open Graph](http://ogp.me/) metadata.


================================================
FILE: themes/hermit/exampleSite/content/posts/the-figure-shortcode.md
================================================
---
title: 'The "figure" Shortcode'
date: 2018-12-24T12:29:41+08:00
draft: false
featuredImg: ""
tags: 
  - demo
  - image
---

Hugo has `figure` shortcode built in, so you can easily add figcaptions or hyperlink rel attributes to images. Documentations can be found here:

https://gohugo.io/content-management/shortcodes/#figure

This theme has 3 CSS classes made for figure elements:

* `big`: images will break the width limit of main content area.
* `left`: images will float to the left.
* `right`: images will float to the right.

If a figure has no class set, the image will behave just like a normal markdown image: `![]()`.

Here's some examples, please be aware that these styles only take effect when the page width is over 1300px.

{{< figure src="https://via.placeholder.com/1600x800" alt="image" caption="figure-normal (without any classes)" >}}

Pellentesque posuere sem nec nunc varius, id hendrerit arcu consequat. Maecenas commodo, sapien ut gravida porttitor, dolor risus facilisis enim, eget pharetra nibh nisl porttitor sapien. Proin finibus elementum ligula sit amet hendrerit. Praesent et erat sodales ante accumsan pharetra non eu nulla. Sed vehicula consequat lorem, a fermentum ante faucibus quis. Aliquam erat volutpat. In vitae tincidunt dui. Proin sit amet ligula sodales, elementum tortor et, venenatis sem. Maecenas non nisl erat. Curabitur nec velit eros. Ut cursus lacus nisi, non pretium libero euismod et. Fusce luctus in nisi quis sollicitudin. Aenean nec blandit ligula. Duis ac felis lorem. Proin tellus tellus, dictum nec tempus sit amet, venenatis ac felis. Sed in pharetra nulla, non mollis sem.

{{< figure src="https://via.placeholder.com/1600x800" alt="image" caption="figure-big" class="big" >}}

Suspendisse fringilla malesuada massa, in malesuada orci lacinia a. Praesent dapibus faucibus nisl, id volutpat elit bibendum eu. Nulla vitae laoreet nibh, eu hendrerit lacus. Donec lacinia auctor ligula, vel interdum ipsum malesuada vitae. Donec placerat a justo eu gravida. Aenean ultricies imperdiet convallis. Pellentesque accumsan non ex sed euismod. Proin bibendum lectus nec enim faucibus feugiat. Donec hendrerit nisi viverra ornare luctus. Nullam non viverra nisl. Nam vel tellus et tortor elementum volutpat sit amet et erat. Aliquam a libero quis libero porta consectetur. Etiam aliquam felis vel nulla mattis finibus. Mauris laoreet lacus arcu, sed rhoncus odio condimentum sed. Aenean in dui rutrum elit faucibus faucibus nec fringilla augue. Fusce non ornare mauris.

{{< figure src="https://via.placeholder.com/400x280" alt="image" caption="figure-left" class="left" >}}

In a libero varius, luctus ligula et, bibendum tortor. Sed sit amet dui malesuada, mattis justo id, ultricies enim. Vestibulum ante ipsum primis in faucibus orci luctus et ultrices posuere cubilia Curae; Aliquam sollicitudin cursus feugiat. Vivamus suscipit ipsum eget lobortis sollicitudin. Fusce vehicula neque tellus. Integer eu posuere quam, id laoreet tortor. Mauris sit amet turpis urna. Donec venenatis tempor dolor, nec laoreet orci aliquet et. Sed condimentum elit eu tristique aliquam. Pellentesque habitant morbi tristique senectus et netus et malesuada fames ac turpis egestas. Nunc luctus ipsum sit amet nisl maximus pellentesque.

{{< figure src="https://via.placeholder.com/400x280" alt="image" caption="figure-right" class="right" >}}

Pellentesque eu consequat nunc. Vivamus eu eros ut nulla dapibus molestie in id tortor. Cras viverra ligula erat, tincidunt hendrerit diam blandit nec. Cras id urna vel dolor dictum mattis. Vestibulum congue erat ac eros molestie accumsan. Maecenas lorem nibh, maximus vel justo eget, facilisis egestas lectus. Mauris eu est ut odio blandit consequat id feugiat eros. Fusce id suscipit mi, et lacinia lectus. Mauris a arcu placerat dolor iaculis feugiat nec non mi. Ut porttitor elit tortor, eget tempus velit mollis eu. Aliquam sem nulla, dictum cursus mauris ac, semper ullamcorper leo.

Donec nec tincidunt est. Sed id metus in erat fringilla mattis at id turpis. Aliquam tempor vehicula faucibus. Phasellus consequat aliquam odio. Morbi a ex vitae sapien porta auctor. Orci varius natoque penatibus et magnis dis parturient montes, nascetur ridiculus mus. Donec sit amet nulla arcu. Praesent ut tortor purus. Praesent id eros diam. Pellentesque vitae dolor at nibh ultrices accumsan eu id urna. Aliquam finibus interdum orci in varius. Pellentesque a enim condimentum, condimentum felis id, vehicula augue. Vivamus cursus commodo eros nec lacinia.


================================================
FILE: themes/hermit/exampleSite/content/posts/typography.md
================================================
---
title: "Typography"
date: 2018-09-29T11:36:33+08:00
draft: false
featuredImg: ""
tags: 
  - Demo
  - Typography
---

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.

> An apple is a sweet, edible fruit produced by an apple tree (Malus pumila). Apple trees are cultivated worldwide, and are the most widely grown species in the genus Malus. The tree originated in Central Asia, where its wild ancestor, Malus sieversii, is still found today. Apples have been grown for thousands of years in Asia and Europe, and were brought to North America by European colonists. Apples have religious and mythological significance in many cultures, including Norse, Greek and European Christian traditions.[^1]

---

Inline styles：

**strong**, *emphasis*, ***strong and emphasis***,`code`, <u>underline</u>, ~~strikethrough~~, :joy:🤣, $\LaTeX$, X^2^, H~2~O, ==highlight==, [Link](https://example.com), and image:

![img](https://picsum.photos/600/400/?random)

---

Headings:

# Heading 1

## Heading 2

### Heading 3

#### Heading 4

##### Heading 5

###### Heading 6

Table:

| Left-Aligned  | Center Aligned  | Right Aligned |
| :------------ | :-------------: | ------------: |
| col 3 is      | some wordy text |         $1600 |
| col 2 is      |    centered     |           $12 |
| zebra stripes |    are neat     |            $1 |

Lists:

* Unordered list item 1.
* Unordered list item 2.

1. ordered list item 1.
2. ordered list item 2.
   + sub-unordered list item 1.
   + sub-unordered list item 2.
     + [x] something is DONE.
     + [ ] something is NOT DONE.

Syntax Highlighting:

```javascript
var num1, num2, sum
num1 = prompt("Enter first number")
num2 = prompt("Enter second number")
sum = parseInt(num1) + parseInt(num2) // "+" means "add"
alert("Sum = " + sum)  // "+" means combine into a string
```

[^1]: From https://en.wikipedia.org/wiki/Apple

================================================
FILE: themes/hermit/i18n/en.toml
================================================
# Translations for English
# https://gohugo.io/content-management/multilingual/#translation-of-strings

# 404.html
#
[notFound]
other = "Oops, page not found…"

[home]
other = "Home"

[archives]
other = "Archives"

# posts/single.html
#
[wordCount]
other = "{{ .WordCount }} Words"

[tableOfContents]
other = "Table of Contents"

[newer]
other = "Newer"

[older]
other = "Older"

# partials/header.html
#
[menu]
other = "Menu"

[featuredImage]
other = "Featured Image"


================================================
FILE: themes/hermit/i18n/it.toml
================================================
# Translations for Italian
# https://gohugo.io/content-management/multilingual/#translation-of-strings

# 404.html
#
[notFound]
other = "Oops, pagina non trovata…"

[home]
other = "Home"

[archives]
other = "Archivi"

# posts/single.html
#
[wordCount]
other = "{{ .WordCount }} Parole"

[tableOfContents]
other = "Sommario"

[newer]
other = "Prossimo"

[older]
other = "Precedente"

# partials/header.html
#
[menu]
other = "Menu"

[featuredImage]
other = "Immagine in primo piano"


================================================
FILE: themes/hermit/i18n/zh-hans.toml
================================================
# Translations for Simplified Chinese - 简体中文
# https://gohugo.io/content-management/multilingual/#translation-of-strings

# 404.html
#
[notFound]
other = "糟糕，您要访问的页面不存在……"

[home]
other = "主页"

[archives]
other = "归档"

# posts/single.html
#
[wordCount]
other = "{{ .WordCount }} 字"

[tableOfContents]
other = "目录"

[newer]
other = "新"

[older]
other = "旧"

# partials/header.html
#
[menu]
other = "菜单"

[featuredImage]
other = "特色图片"


================================================
FILE: themes/hermit/layouts/404.html
================================================
{{ define "main" }}
	<div id="spotlight" class="error-404 animated fadeIn">
		<p class="img-404">
			<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 167.8 163.4" fill="currentColor"><title>404-lighthouse</title><path d="M83,27.5c.5-8.4,12.5-8.4,13,0,.2,3.2,5.2,3.2,5,0C100.7,21.3,96,16,89.5,16S78.3,21.3,78,27.5c-.2,3.2,4.8,3.2,5,0Z" transform="translate(-6.6 -6.6)"/><path d="M92,18V9c0-3.2-5-3.2-5,0v9c0,3.2,5,3.2,5,0Z" transform="translate(-6.6 -6.6)"/><path d="M78,44.5l-7.9,86.7L69,143.5c-.3,3.2,4.7,3.2,5,0l7.9-86.7L83,44.5c.3-3.2-4.7-3.2-5,0Z" transform="translate(-6.6 -6.6)"/><path d="M96,44.5l7.9,86.7,1.1,12.3c.3,3.2,5.3,3.2,5,0l-7.9-86.7L101,44.5c-.3-3.2-5.3-3.2-5,0Z" transform="translate(-6.6 -6.6)"/><path d="M88.5,26.5v18a1,1,0,0,0,2,0v-18a1,1,0,0,0-2,0Z" transform="translate(-6.6 -6.6)"/><path d="M79.1,69.6l21.2-12.2a1.5,1.5,0,0,0-1.5-2.6L77.6,67a1.5,1.5,0,0,0,1.5,2.6Z" transform="translate(-6.6 -6.6)"/><path d="M76.4,99.2,102.7,84a1.5,1.5,0,0,0-1.5-2.6L74.9,96.6a1.5,1.5,0,0,0,1.5,2.6Z" transform="translate(-6.6 -6.6)"/><path d="M73.7,128.7l31.4-18.1a1.5,1.5,0,0,0-1.5-2.6L72.2,126.1a1.5,1.5,0,0,0,1.5,2.6Z" transform="translate(-6.6 -6.6)"/><path d="M98.5,42h-18L83,44.5v-18L80.5,29h18L96,26.5v18c0,3.2,5,3.2,5,0v-18A2.5,2.5,0,0,0,98.5,24h-18A2.5,2.5,0,0,0,78,26.5v18A2.5,2.5,0,0,0,80.5,47h18C101.7,47,101.7,42,98.5,42Z" transform="translate(-6.6 -6.6)"/><path d="M172,165c-5.8-.3-9.5-4.7-15.8-3.8-2.6.4-4.4,1.6-6.7,2.7s-6.9,1.3-10.2-.5-9.5-3.2-14.3-1c-3.3,1.5-5.6,3.3-9.5,2.4-2.4-.5-4.3-2.3-6.7-3.1a15.5,15.5,0,0,0-8.3-.3c-2.5.6-4.3,2.2-6.7,3.1-6.2,2.2-10.8-3.5-16.9-3.5s-10.7,5.6-17,3.5c-2.3-.8-4.2-2.5-6.7-3.1a15.4,15.4,0,0,0-8.3.3c-3.1,1-5.4,3.3-8.9,3.3s-5.8-2.2-8.9-3.3a15.4,15.4,0,0,0-8.8-.2c-3.4,1-5.7,3.3-9.5,3.5s-3.2,5.2,0,5c6-.3,10.9-5.5,17-3.5,2.4.8,4.2,2.5,6.7,3.1a15.4,15.4,0,0,0,8.3-.3c2.3-.8,4.2-2.5,6.7-3.1s6.3.9,9.5,2.4c4.8,2.3,9.8,1.5,14.3-1s6.7-2.2,10.2-.5,4.1,2.3,6.7,2.7a14.9,14.9,0,0,0,7.9-1c2.7-1.2,4.8-2.9,7.9-2.9s5.2,1.7,7.9,2.9a14.9,14.9,0,0,0,7.9,1c2.6-.4,4.4-1.6,6.7-2.7s6.9-1.3,10.2.5a15.9,15.9,0,0,0,16.1,0c7.3-3.9,11.9,2,19.1,2.3,3.2.2,3.2-4.8,0-5Z" transform="translate(-6.6 -6.6)"/><path d="M46.3,165.8l9.6-9.3c4.9-4.6,9.7-11.1,17.2-9.2,4.9,1.2,9.2,5.5,13,8.5s8,6.5,12.1,9.7c2.6,2,5-2.4,2.5-4.3-5-3.8-9.7-7.9-14.7-11.7s-8.7-7-14.6-7.6-11.2,3.6-15.9,8S47,158,42.7,162.2c-2.3,2.3,1.2,5.8,3.5,3.5Z" transform="translate(-6.6 -6.6)"/><path d="M84.8,152.8c8.3-3.7,16.7-8.3,26.1-5.6s15.5,9,19.4,16.6c1.5,2.9,5.8.3,4.3-2.5-4.5-8.7-12.9-16.2-22.4-18.9s-20.3,1.7-29.9,6.1c-2.9,1.3-.4,5.6,2.5,4.3Z" transform="translate(-6.6 -6.6)"/><g class="animated flash infinite slower" ><path d="M62.5,34h-23a1.5,1.5,0,0,0,0,3h23a1.5,1.5,0,0,0,0-3Z" transform="translate(-6.6 -6.6)"/><path d="M63.3,25.2l-18-9c-1.7-.9-3.2,1.7-1.5,2.6l18,9c1.7.9,3.2-1.7,1.5-2.6Z" transform="translate(-6.6 -6.6)"/><path d="M61.7,43.2l-18,9c-1.7.9-.2,3.5,1.5,2.6l18-9c1.7-.9.2-3.5-1.5-2.6Z" transform="translate(-6.6 -6.6)"/><path d="M116.5,37h23a1.5,1.5,0,0,0,0-3h-23a1.5,1.5,0,0,0,0,3Z" transform="translate(-6.6 -6.6)"/><path d="M117.3,27.8l18-9c1.7-.9.2-3.5-1.5-2.6l-18,9c-1.7.9-.2,3.5,1.5,2.6Z" transform="translate(-6.6 -6.6)"/><path d="M115.7,45.8l18,9c1.7.9,3.2-1.7,1.5-2.6l-18-9c-1.7-.9-3.2,1.7-1.5,2.6Z" transform="translate(-6.6 -6.6)"/></g></svg>
		</p>
		<div class="banner-404">
			<h1>404</h1>
			<p>{{ i18n "notFound" }}</p>
			<p class="btn-404">
				<a href="{{.Site.BaseURL}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-home"><path d="M3 9l9-7 9 7v11a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"></path><polyline points="9 22 9 12 15 12 15 22"></polyline></svg>{{ i18n "home" }}</a>
				<a href="{{ "post" | absURL }}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-archive"><polyline points="21 8 21 21 3 21 3 8"></polyline><rect x="1" y="3" width="22" height="5"></rect><line x1="10" y1="12" x2="14" y2="12"></line></svg>{{ i18n "archives" }}</a>
			</p>
		</div>
	</div>
{{ end }}


================================================
FILE: themes/hermit/layouts/_default/baseof.html
================================================
<!DOCTYPE html>
<html lang="{{.Site.LanguageCode}}">

<head>
	<meta charset="UTF-8">
	<meta name="viewport" content="width=device-width, initial-scale=1.0">
	<meta http-equiv="X-UA-Compatible" content="ie=edge">
	{{- with .Site.Params.themeColor }}
	<meta name="theme-color" content="{{.}}">
	<meta name="msapplication-TileColor" content="{{.}}">
	{{- end }}
	{{- partial "structured-data.html" . }}
	{{- partial "favicons.html" }}
	<title>{{.Title}}</title>
	{{ range .AlternativeOutputFormats -}}
		{{ printf `<link rel="%s" type="%s+%s" href="%s" title="%s" />` .Rel .MediaType.Type .MediaType.Suffix .Permalink $.Site.Title | safeHTML }}
	{{ end -}}
	{{ $style := resources.Get "scss/style.scss" | resources.ExecuteAsTemplate "css/style.css" . | toCSS | minify | fingerprint -}}
	<link rel="stylesheet" href="{{ $style.Permalink }}">
	{{- block "head" . -}}{{- end }}
	{{- range .Site.Params.customCSS }}
	<link rel="stylesheet" href="{{ . | absURL }}">
	{{- end }}
	{{- if templates.Exists "partials/extra-head.html" -}}
	{{ partial "extra-head.html" . }}
	{{- end }}
</head>

<body id="page">
	{{ block "header" . -}}{{ end -}}
	{{ block "main" . -}}{{ end -}}
	{{ block "footer" . -}}{{ end }}
	{{ $script := resources.Get "js/main.js" | minify | fingerprint -}}
	<script src="{{ $script.Permalink }}"></script>
	{{- partial "analytics.html" . }}
	{{- if templates.Exists "partials/extra-foot.html" -}}
	{{ partial "extra-foot.html" . }}
	{{- end }}
</body>

</html>


================================================
FILE: themes/hermit/layouts/_default/list.html
================================================
{{ define "header" }}
{{ partialCached "header.html" . }}
{{ end }}

{{ define "main" }}
	<main class="site-main section-inner thin animated fadeIn faster">
		<h1>{{ .Title }}</h1>
		{{- if .Content }}
		<div class="content">
			{{ .Content }}
		</div>
		{{- end }}
		{{- range .Data.Pages.GroupByDate "2006" }}
		<div class="posts-group">
			<div class="post-year" id="{{ .Key }}">{{ .Key }}</div>
			<ul class="posts-list">
				{{- range .Pages }}
				<li class="post-item">
					<a href="{{.Permalink}}">
						<span class="post-title">{{.Title}}</span>
						<span class="post-day">{{ .Date.Format .Site.Params.dateformShort }}</span>
					</a>
				</li>
				{{- end }}
			</ul>
		</div>
		{{- end }}
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: themes/hermit/layouts/_default/single.html
================================================
{{ define "head" }}
	{{ if .Params.featuredImg -}}
	<style>.bg-img {background-image: url('{{.Params.featuredImg}}');}</style>
	{{- else if .Params.images -}}
		{{- range first 1 .Params.images -}}
		<style>.bg-img {background-image: url('{{. | absURL}}');}</style>
		{{- end -}}
	{{- end -}}
{{ end }}

{{ define "header" }}
{{ partial "header.html" . }}
{{ end }}

{{ define "main" }}
	{{- if (or .Params.images .Params.featuredImg) }}
	<div class="bg-img"></div>
	{{- end }}
	<main class="site-main section-inner thin animated fadeIn faster">
		<h1>{{ .Title }}</h1>
		<div class="content">
			{{ .Content | replaceRE "(<h[1-6] id=\"([^\"]+)\".+)(</h[1-6]+>)" `${1}<a href="#${2}" class="anchor" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 7h3a5 5 0 0 1 5 5 5 5 0 0 1-5 5h-3m-6 0H6a5 5 0 0 1-5-5 5 5 0 0 1 5-5h3"></path><line x1="8" y1="12" x2="16" y2="12"></line></svg></a>${3}` | safeHTML }}
		</div>
		{{- if .Params.comments }}
		<div id="comments" class="thin">
			{{ partial "comments.html" . }}
		</div>
		{{- end }}
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: themes/hermit/layouts/index.html
================================================
{{ define "head" }}
	{{ if .Site.Params.bgImg -}}
	<style>.bg-img {background-image: url('{{.Site.Params.bgImg}}');}</style>
	{{- else if .Site.Params.images -}}
		{{- range first 1 .Site.Params.images -}}
		<style>.bg-img {background-image: url('{{. | absURL}}');}</style>
		{{- end -}}
	{{- end -}}
{{ end }}

{{ define "main" }}
	{{- if (or .Site.Params.images .Site.Params.bgImg) }}
	<div class="bg-img"></div>
	{{- end }}
	<div id="spotlight" class="animated fadeIn">
		<div id="home-center">
			<h1 id="home-title">{{ .Site.Title }}</h1>
			{{- with .Site.Params.homeSubtitle }}
			<p id="home-subtitle">{{.}}</p>
			{{- end }}
			{{- with .Site.Params.social }}
			<div id="home-social">
				{{ partialCached "social-icons.html" . }}
			</div>
			{{- end }}
			<nav id="home-nav" class="site-nav">
				{{- range .Site.Menus.main }}
				<a href="{{ .URL | absLangURL }}">{{ .Name }}</a>
				{{- end }}
			</nav>
		</div>
		<div id="home-footer">
			<p>
				&copy; {{ now.Format "2006" }} <a href="{{ .Site.BaseURL }}">{{ .Site.Author.name }}</a>{{ .Site.Params.footerCopyright | safeHTML }}
				{{- with (not (in (.Site.Language.Get "disableKinds") "RSS")) }} &#183; <a href="{{ "post/index.xml" | absURL }}" target="_blank" title="rss"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-rss"><path d="M4 11a9 9 0 0 1 9 9"></path><path d="M4 4a16 16 0 0 1 16 16"></path><circle cx="5" cy="19" r="1"></circle></svg></a>{{ end }}
			</p>
		</div>
	</div>
{{ end }}


================================================
FILE: themes/hermit/layouts/partials/analytics.html
================================================
{{ template "_internal/google_analytics_async.html" . }}


================================================
FILE: themes/hermit/layouts/partials/favicons.html
================================================
	<link rel="apple-touch-icon" sizes="180x180" href="{{"apple-touch-icon.png" | relURL}}">
	<link rel="icon" type="image/png" sizes="32x32" href="{{"favicon-32x32.png" | relURL}}">
	<link rel="icon" type="image/png" sizes="16x16" href="{{"favicon-16x16.png" | relURL}}">
	<link rel="manifest" href="{{"site.webmanifest" | relURL}}">
	<link rel="mask-icon" href="{{"safari-pinned-tab.svg" | relURL}}" color="{{.Site.Params.themeColor}}">
	<link rel="shortcut icon" href="{{"favicon.ico" | relURL}}">


================================================
FILE: themes/hermit/layouts/partials/footer.html
================================================
	<footer id="site-footer" class="section-inner thin animated fadeIn faster">
		<p>&copy; {{ now.Format "2006" }} <a href="{{ .Site.BaseURL }}">{{ .Site.Author.name }}</a>{{ .Site.Params.footerCopyright | safeHTML }}</p>
		<p>
			Made with <a href="https://gohugo.io/" target="_blank" rel="noopener">Hugo</a> &#183; Theme <a href="https://github.com/Track3/hermit" target="_blank" rel="noopener">Hermit</a>
			{{- with (not (in (.Site.Language.Get "disableKinds") "RSS")) }} &#183; <a href="{{ "post/index.xml" | absURL }}" target="_blank" title="rss"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-rss"><path d="M4 11a9 9 0 0 1 9 9"></path><path d="M4 4a16 16 0 0 1 16 16"></path><circle cx="5" cy="19" r="1"></circle></svg></a>{{ end }}
		</p>
	</footer>


================================================
FILE: themes/hermit/layouts/partials/header.html
================================================
	<header id="site-header" class="animated slideInUp faster">
		<div class="hdr-wrapper section-inner">
			<div class="hdr-left">
				<div class="site-branding">
					<a href="{{.Site.BaseURL}}">{{ .Site.Title }}</a>
				</div>
				<nav class="site-nav hide-in-mobile">
					{{- range .Site.Menus.main }}
					<a href="{{ .URL | absLangURL}}">{{ .Name }}</a>
					{{- end }}
				</nav>
			</div>
			<div class="hdr-right hdr-icons">
				{{ if (or .Params.images .Params.featuredImg) -}}
				<button id="img-btn" class="hdr-btn" title="{{i18n "featuredImage"}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-image"><rect x="3" y="3" width="18" height="18" rx="2" ry="2"></rect><circle cx="8.5" cy="8.5" r="1.5"></circle><polyline points="21 15 16 10 5 21"></polyline></svg></button>
				{{- end }}
				{{- with .Params.toc -}}
				<button id="toc-btn" class="hdr-btn desktop-only-ib" title="{{i18n "tableOfContents"}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-list"><line x1="8" y1="6" x2="21" y2="6"></line><line x1="8" y1="12" x2="21" y2="12"></line><line x1="8" y1="18" x2="21" y2="18"></line><line x1="3" y1="6" x2="3" y2="6"></line><line x1="3" y1="12" x2="3" y2="12"></line><line x1="3" y1="18" x2="3" y2="18"></line></svg></button>
				{{- end }}
				{{- with .Site.Params.social -}}
				<span class="hdr-social hide-in-mobile">{{ partialCached "social-icons.html" . }}</span>
				{{- end -}}
				<button id="menu-btn" class="hdr-btn" title="{{i18n "menu"}}"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-menu"><line x1="3" y1="12" x2="21" y2="12"></line><line x1="3" y1="6" x2="21" y2="6"></line><line x1="3" y1="18" x2="21" y2="18"></line></svg></button>
			</div>
		</div>
	</header>
	<div id="mobile-menu" class="animated fast">
		<ul>
			{{- range .Site.Menus.main }}
			<li><a href="{{ .URL | absLangURL }}">{{ .Name }}</a></li>
			{{- end }}
		</ul>
	</div>


================================================
FILE: themes/hermit/layouts/partials/social-icons.html
================================================
{{ range . -}}
<a href="{{ .url }}" target="_blank" rel="noopener me" title="{{ .name | humanize }}">{{ partial "svg.html" . }}</a>
{{- end -}}


================================================
FILE: themes/hermit/layouts/partials/structured-data.html
================================================
{{/* We use some Hugo built-in templates, you can find their source here: */}}
{{/* https://github.com/gohugoio/hugo/tree/master/tpl/tplimpl/embedded/templates */}}

{{- template "_internal/schema.html" . }}
{{- template "_internal/opengraph.html" . }}
{{- template "_internal/twitter_cards.html" . }}


================================================
FILE: themes/hermit/layouts/partials/svg.html
================================================
{{- if (eq .name "codepen") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-codepen"><polygon points="12 2 22 8.5 22 15.5 12 22 2 15.5 2 8.5 12 2"></polygon><line x1="12" y1="22" x2="12" y2="15.5"></line><polyline points="22 8.5 12 15.5 2 8.5"></polyline><polyline points="2 15.5 12 8.5 22 15.5"></polyline><line x1="12" y1="2" x2="12" y2="8.5"></line></svg>
{{- else if (eq .name "facebook") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-facebook"><path d="M18 2h-3a5 5 0 0 0-5 5v3H7v4h3v8h4v-8h3l1-4h-4V7a1 1 0 0 1 1-1h3z"></path></svg>
{{- else if (eq .name "github") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-github"><path d="M9 19c-5 1.5-5-2.5-7-3m14 6v-3.87a3.37 3.37 0 0 0-.94-2.61c3.14-.35 6.44-1.54 6.44-7A5.44 5.44 0 0 0 20 4.77 5.07 5.07 0 0 0 19.91 1S18.73.65 16 2.48a13.38 13.38 0 0 0-7 0C6.27.65 5.09 1 5.09 1A5.07 5.07 0 0 0 5 4.77a5.44 5.44 0 0 0-1.5 3.78c0 5.42 3.3 6.61 6.44 7A3.37 3.37 0 0 0 9 18.13V22"></path></svg>
{{- else if (eq .name "gitlab") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-gitlab"><path d="M22.65 14.39L12 22.13 1.35 14.39a.84.84 0 0 1-.3-.94l1.22-3.78 2.44-7.51A.42.42 0 0 1 4.82 2a.43.43 0 0 1 .58 0 .42.42 0 0 1 .11.18l2.44 7.49h8.1l2.44-7.51A.42.42 0 0 1 18.6 2a.43.43 0 0 1 .58 0 .42.42 0 0 1 .11.18l2.44 7.51L23 13.45a.84.84 0 0 1-.35.94z"></path></svg>
{{- else if (eq .name "instagram") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-instagram"><rect x="2" y="2" width="20" height="20" rx="5" ry="5"></rect><path d="M16 11.37A4 4 0 1 1 12.63 8 4 4 0 0 1 16 11.37z"></path><line x1="17.5" y1="6.5" x2="17.5" y2="6.5"></line></svg>
{{- else if (eq .name "linkedin") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-linkedin"><path d="M16 8a6 6 0 0 1 6 6v7h-4v-7a2 2 0 0 0-2-2 2 2 0 0 0-2 2v7h-4v-7a6 6 0 0 1 6-6z"></path><rect x="2" y="9" width="4" height="12"></rect><circle cx="4" cy="4" r="2"></circle></svg>
{{- else if (eq .name "slack") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-slack"><path d="M22.08 9C19.81 1.41 16.54-.35 9 1.92S-.35 7.46 1.92 15 7.46 24.35 15 22.08 24.35 16.54 22.08 9z"></path><line x1="12.57" y1="5.99" x2="16.15" y2="16.39"></line><line x1="7.85" y1="7.61" x2="11.43" y2="18.01"></line><line x1="16.39" y1="7.85" x2="5.99" y2="11.43"></line><line x1="18.01" y1="12.57" x2="7.61" y2="16.15"></line></svg>
{{- else if (eq .name "telegram") -}}
<svg width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-linecap="round" stroke-linejoin="round" stroke-width="2" aria-hidden="true" class="feather"><path d="m 22.05,1.577 c -0.393,-0.016 -0.784,0.08 -1.117,0.235 -0.484,0.186 -4.92,1.902 -9.41,3.64 C 9.263,6.325 7.005,7.198 5.267,7.867 3.53,8.537 2.222,9.035 2.153,9.059 c -0.46,0.16 -1.082,0.362 -1.61,0.984 -0.79581202,1.058365 0.21077405,1.964825 1.004,2.499 1.76,0.564 3.58,1.102 5.087,1.608 0.556,1.96 1.09,3.927 1.618,5.89 0.174,0.394 0.553,0.54 0.944,0.544 l -0.002,0.02 c 0,0 0.307,0.03 0.606,-0.042 0.3,-0.07 0.677,-0.244 1.02,-0.565 0.377,-0.354 1.4,-1.36 1.98,-1.928 l 4.37,3.226 0.035,0.02 c 0,0 0.484,0.34 1.192,0.388 0.354,0.024 0.82,-0.044 1.22,-0.337 0.403,-0.294 0.67,-0.767 0.795,-1.307 0.374,-1.63 2.853,-13.427 3.276,-15.38 L 23.676,4.725 C 23.972,3.625 23.863,2.617 23.18,2.02 22.838,1.723 22.444,1.593 22.05,1.576 Z"></path></svg>
{{- else if (eq .name "twitter") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-twitter"><path d="M23 3a10.9 10.9 0 0 1-3.14 1.53 4.48 4.48 0 0 0-7.86 3v1A10.66 10.66 0 0 1 3 4s-4 9 5 13a11.64 11.64 0 0 1-7 2c9 5 20 0 20-11.5a4.5 4.5 0 0 0-.08-.83A7.72 7.72 0 0 0 23 3z"></path></svg>
{{- else if (eq .name "youtube") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-youtube"><path d="M22.54 6.42a2.78 2.78 0 0 0-1.94-2C18.88 4 12 4 12 4s-6.88 0-8.6.46a2.78 2.78 0 0 0-1.94 2A29 29 0 0 0 1 11.75a29 29 0 0 0 .46 5.33A2.78 2.78 0 0 0 3.4 19c1.72.46 8.6.46 8.6.46s6.88 0 8.6-.46a2.78 2.78 0 0 0 1.94-2 29 29 0 0 0 .46-5.25 29 29 0 0 0-.46-5.33z"></path><polygon points="9.75 15.02 15.5 11.75 9.75 8.48 9.75 15.02"></polygon></svg>
{{- else if (eq .name "email") -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-mail"><path d="M4 4h16c1.1 0 2 .9 2 2v12c0 1.1-.9 2-2 2H4c-1.1 0-2-.9-2-2V6c0-1.1.9-2 2-2z"></path><polyline points="22,6 12,13 2,6"></polyline></svg>
{{- else -}}
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-link"><path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path><path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path></svg>
{{- end -}}


================================================
FILE: themes/hermit/layouts/post/rss.xml
================================================
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
		<link>{{ .Permalink }}</link>
		<description>Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
		<generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
		<language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
		<managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
		<webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
		<copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
		<lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
		{{ with .OutputFormats.Get "RSS" -}}
			{{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
		{{ end -}}
		{{ range .Pages }}
		<item>
			<title>{{ .Title }}</title>
			<link>{{ .Permalink }}</link>
			<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
			{{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
			<guid>{{ .Permalink }}</guid>
			<description>{{ .Summary | html }}</description>
			<content type="html">{{ printf `<![CDATA[%s]]>` .Content | safeHTML }}</content>
		</item>
		{{ end }}
	</channel>
</rss>


================================================
FILE: themes/hermit/layouts/post/single.html
================================================
{{ define "head" }}
	{{ if .Params.featuredImg -}}
	<style>.bg-img {background-image: url('{{.Params.featuredImg}}');}</style>
	{{- else if .Params.images -}}
		{{- range first 1 .Params.images -}}
		<style>.bg-img {background-image: url('{{. | absURL}}');}</style>
		{{- end -}}
	{{- end -}}
{{ end }}

{{ define "header" }}
{{ partial "header.html" . }}
{{ end }}

{{ define "main" }}
	{{- if (or .Params.images .Params.featuredImg) }}
	<div class="bg-img"></div>
	{{- end }}
	<main class="site-main section-inner animated fadeIn faster">
		<article class="thin">
			<header class="post-header">
				<div class="post-meta"><span>{{ .Date.Format .Site.Params.dateform }}</span></div>
				<h1>{{ .Title }}</h1>
			</header>
			<div class="content">
				{{ .Content | replaceRE "(<h[1-6] id=\"([^\"]+)\".+)(</h[1-6]+>)" `${1}<a href="#${2}" class="anchor" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 7h3a5 5 0 0 1 5 5 5 5 0 0 1-5 5h-3m-6 0H6a5 5 0 0 1-5-5 5 5 0 0 1 5-5h3"></path><line x1="8" y1="12" x2="16" y2="12"></line></svg></a>${3}` | safeHTML }}
			</div>
			<hr class="post-end">
			<footer class="post-info">
				{{- with .Params.tags }}
				<p>
					<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-tag meta-icon"><path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z"></path><line x1="7" y1="7" x2="7" y2="7"></line></svg>
					{{- range . -}}
					<span class="tag"><a href="{{ "tags/" | absURL }}{{ . | urlize }}">{{.}}</a></span>
					{{- end }}
				</p>
				{{- end }}
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file-text"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path><polyline points="14 2 14 8 20 8"></polyline><line x1="16" y1="13" x2="8" y2="13"></line><line x1="16" y1="17" x2="8" y2="17"></line><polyline points="10 9 9 9 8 9"></polyline></svg>{{ i18n "wordCount" . }}</p>
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-calendar"><rect x="3" y="4" width="18" height="18" rx="2" ry="2"></rect><line x1="16" y1="2" x2="16" y2="6"></line><line x1="8" y1="2" x2="8" y2="6"></line><line x1="3" y1="10" x2="21" y2="10"></line></svg>{{ dateFormat .Site.Params.dateformNumTime .Date.Local }}</p>
				{{- if and .GitInfo .Site.Params.gitUrl }}
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-git-commit"><circle cx="12" cy="12" r="4"></circle><line x1="1.05" y1="12" x2="7" y2="12"></line><line x1="17.01" y1="12" x2="22.96" y2="12"></line></svg><a href="{{ .Site.Params.gitUrl -}}{{ .GitInfo.Hash }}" target="_blank" rel="noopener">{{ .GitInfo.AbbreviatedHash }}</a> @ {{ dateFormat .Site.Params.dateformNum .GitInfo.AuthorDate.Local }}</p>
				{{- end }}
			</footer>
		</article>
		{{- if .Params.toc }}
		<aside id="toc" class="show-toc">
			<div class="toc-title">{{ i18n "tableOfContents" }}</div>
			{{ .TableOfContents }}
		</aside>
		{{- end }}
		<div class="post-nav thin">
			{{- with .NextInSection }}
			<a class="next-post" href="{{ .Permalink }}">
				<span class="post-nav-label"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-arrow-left"><line x1="19" y1="12" x2="5" y2="12"></line><polyline points="12 19 5 12 12 5"></polyline></svg>&nbsp;{{ i18n "newer" }}</span><br><span>{{ .Title }}</span>
			</a>
			{{- end }}
			{{- with .PrevInSection }}
			<a class="prev-post" href="{{ .Permalink }}">
				<span class="post-nav-label">{{ i18n "older" }}&nbsp;<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-arrow-right"><line x1="5" y1="12" x2="19" y2="12"></line><polyline points="12 5 19 12 12 19"></polyline></svg></span><br><span>{{ .Title }}</span>
			</a>
			{{- end }}
		</div>
		<div id="comments" class="thin">
			<script src="https://utteranc.es/client.js"
							repo="aylei/blog"
							issue-term="pathname"
							theme="github-light"
							crossorigin="anonymous"
							async>
			</script>
		</div>
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: themes/hermit/layouts/posts/rss.xml
================================================
<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
	<channel>
		<title>{{ if eq  .Title  .Site.Title }}{{ .Site.Title }}{{ else }}{{ with .Title }}{{.}} on {{ end }}{{ .Site.Title }}{{ end }}</title>
		<link>{{ .Permalink }}</link>
		<description>Recent content {{ if ne  .Title  .Site.Title }}{{ with .Title }}in {{.}} {{ end }}{{ end }}on {{ .Site.Title }}</description>
		<generator>Hugo -- gohugo.io</generator>{{ with .Site.LanguageCode }}
		<language>{{.}}</language>{{end}}{{ with .Site.Author.email }}
		<managingEditor>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</managingEditor>{{end}}{{ with .Site.Author.email }}
		<webMaster>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</webMaster>{{end}}{{ with .Site.Copyright }}
		<copyright>{{.}}</copyright>{{end}}{{ if not .Date.IsZero }}
		<lastBuildDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</lastBuildDate>{{ end }}
		{{ with .OutputFormats.Get "RSS" -}}
			{{ printf "<atom:link href=%q rel=\"self\" type=%q />" .Permalink .MediaType | safeHTML }}
		{{ end -}}
		{{ range .Pages }}
		<item>
			<title>{{ .Title }}</title>
			<link>{{ .Permalink }}</link>
			<pubDate>{{ .Date.Format "Mon, 02 Jan 2006 15:04:05 -0700" | safeHTML }}</pubDate>
			{{ with .Site.Author.email }}<author>{{.}}{{ with $.Site.Author.name }} ({{.}}){{end}}</author>{{end}}
			<guid>{{ .Permalink }}</guid>
			<description>{{ .Summary | html }}</description>
			<content type="html">{{ printf `<![CDATA[%s]]>` .Content | safeHTML }}</content>
		</item>
		{{ end }}
	</channel>
</rss>


================================================
FILE: themes/hermit/layouts/posts/single.html
================================================
{{ define "head" }}
	{{ if .Params.featuredImg -}}
	<style>.bg-img {background-image: url('{{.Params.featuredImg}}');}</style>
	{{- else if .Params.images -}}
		{{- range first 1 .Params.images -}}
		<style>.bg-img {background-image: url('{{. | absURL}}');}</style>
		{{- end -}}
	{{- end -}}
{{ end }}

{{ define "header" }}
{{ partial "header.html" . }}
{{ end }}

{{ define "main" }}
	{{- if (or .Params.images .Params.featuredImg) }}
	<div class="bg-img"></div>
	{{- end }}
	<main class="site-main section-inner animated fadeIn faster">
		<article class="thin">
			<header class="post-header">
				<div class="post-meta"><span>{{ .Date.Format .Site.Params.dateform }}</span></div>
				<h1>{{ .Title }}</h1>
			</header>
			<div class="content">
				{{ .Content | replaceRE "(<h[1-6] id=\"([^\"]+)\".+)(</h[1-6]+>)" `${1}<a href="#${2}" class="anchor" aria-hidden="true"><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><path d="M15 7h3a5 5 0 0 1 5 5 5 5 0 0 1-5 5h-3m-6 0H6a5 5 0 0 1-5-5 5 5 0 0 1 5-5h3"></path><line x1="8" y1="12" x2="16" y2="12"></line></svg></a>${3}` | safeHTML }}
			</div>
			<hr class="post-end">
			<footer class="post-info">
				{{- with .Params.tags }}
				<p>
					<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-tag meta-icon"><path d="M20.59 13.41l-7.17 7.17a2 2 0 0 1-2.83 0L2 12V2h10l8.59 8.59a2 2 0 0 1 0 2.82z"></path><line x1="7" y1="7" x2="7" y2="7"></line></svg>
					{{- range . -}}
					<span class="tag"><a href="{{ "tags/" | absURL }}{{ . | urlize }}">{{.}}</a></span>
					{{- end }}
				</p>
				{{- end }}
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-file-text"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"></path><polyline points="14 2 14 8 20 8"></polyline><line x1="16" y1="13" x2="8" y2="13"></line><line x1="16" y1="17" x2="8" y2="17"></line><polyline points="10 9 9 9 8 9"></polyline></svg>{{ i18n "wordCount" . }}</p>
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-calendar"><rect x="3" y="4" width="18" height="18" rx="2" ry="2"></rect><line x1="16" y1="2" x2="16" y2="6"></line><line x1="8" y1="2" x2="8" y2="6"></line><line x1="3" y1="10" x2="21" y2="10"></line></svg>{{ dateFormat .Site.Params.dateformNumTime .Date.Local }}</p>
				{{- if and .GitInfo .Site.Params.gitUrl }}
				<p><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-git-commit"><circle cx="12" cy="12" r="4"></circle><line x1="1.05" y1="12" x2="7" y2="12"></line><line x1="17.01" y1="12" x2="22.96" y2="12"></line></svg><a href="{{ .Site.Params.gitUrl -}}{{ .GitInfo.Hash }}" target="_blank" rel="noopener">{{ .GitInfo.AbbreviatedHash }}</a> @ {{ dateFormat .Site.Params.dateformNum .GitInfo.AuthorDate.Local }}</p>
				{{- end }}
			</footer>
		</article>
		{{- if .Params.toc }}
		<aside id="toc">
			<div class="toc-title">{{ i18n "tableOfContents" }}</div>
			{{ .TableOfContents }}
		</aside>
		{{- end }}
		<div class="post-nav thin">
			{{- with .NextInSection }}
			<a class="next-post" href="{{ .Permalink }}">
				<span class="post-nav-label"><svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-arrow-left"><line x1="19" y1="12" x2="5" y2="12"></line><polyline points="12 19 5 12 12 5"></polyline></svg>&nbsp;{{ i18n "newer" }}</span><br><span>{{ .Title }}</span>
			</a>
			{{- end }}
			{{- with .PrevInSection }}
			<a class="prev-post" href="{{ .Permalink }}">
				<span class="post-nav-label">{{ i18n "older" }}&nbsp;<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="feather feather-arrow-right"><line x1="5" y1="12" x2="19" y2="12"></line><polyline points="12 5 19 12 12 19"></polyline></svg></span><br><span>{{ .Title }}</span>
			</a>
			{{- end }}
		</div>
		<div id="comments" class="thin">
		{{- partial "comments.html" . -}}
		</div>
	</main>
{{ end }}

{{ define "footer" }}
{{ partialCached "footer.html" . }}
{{ end }}


================================================
FILE: themes/hermit/resources/_gen/assets/js/js/main.js_d11fe7b62c27961c87ecd0f2490357b9.content
================================================
const throttle=(callback,limit)=>{let timeoutHandler=null;return()=>{if(timeoutHandler==null){timeoutHandler=setTimeout(()=>{callback();timeoutHandler=null;},limit);}};};const listen=(ele,e,callback)=>{if(document.querySelector(ele)!==null){document.querySelector(ele).addEventListener(e,callback);}}
let header=document.getElementById('site-header');let lastScrollPosition=window.pageYOffset;const autoHideHeader=()=>{let currentScrollPosition=window.pageYOffset;if(currentScrollPosition>lastScrollPosition){header.classList.remove('slideInUp');header.classList.add('slideOutDown');}else{header.classList.remove('slideOutDown');header.classList.add('slideInUp');}
lastScrollPosition=currentScrollPosition;}
let mobileMenuVisible=false;const toggleMobileMenu=()=>{let mobileMenu=document.getElementById('mobile-menu');if(mobileMenuVisible==false){mobileMenu.style.animationName='bounceInRight';mobileMenu.style.webkitAnimationName='bounceInRight';mobileMenu.style.display='block';mobileMenuVisible=true;}else{mobileMenu.style.animationName='bounceOutRight';mobileMenu.style.webkitAnimationName='bounceOutRight'
mobileMenuVisible=false;}}
const showImg=()=>{document.querySelector('.bg-img').classList.add('show-bg-img');}
const hideImg=()=>{document.querySelector('.bg-img').classList.remove('show-bg-img');}
const toggleToc=()=>{document.getElementById('toc').classList.toggle('show-toc');}
if(header!==null){listen('#menu-btn',"click",toggleMobileMenu);listen('#toc-btn',"click",toggleToc);listen('#img-btn',"click",showImg);listen('.bg-img',"click",hideImg);document.querySelectorAll('.post-year').forEach((ele)=>{ele.addEventListener('click',()=>{window.location.hash='#'+ele.id;});});window.addEventListener('scroll',throttle(()=>{autoHideHeader();if(mobileMenuVisible==true){toggleMobileMenu();}},250));}

================================================
FILE: themes/hermit/resources/_gen/assets/js/js/main.js_d11fe7b62c27961c87ecd0f2490357b9.json
================================================
{"Target":"js/main.min.784417f5847151f848c339cf0acb13a06cbb648b1483435a28ed4556c4ead69b.js","MediaType":"application/javascript","Data":{"Integrity":"sha256-eEQX9YRxUfhIwznPCssToGy7ZIsUg0NaKO1FVsTq1ps="}}

================================================
FILE: themes/hermit/resources/_gen/assets/scss/scss/style.scss_c16d144eee185fbddd582cd5e25a4fae.content
================================================
@charset "UTF-8";/*!normalize.css v8.0.0 | MIT License | github.com/necolas/normalize.css*/html{line-height:1.15;-webkit-text-size-adjust:100%}body{margin:0}h1{font-size:2em;margin:.67em 0}hr{box-sizing:content-box;height:0;overflow:visible}pre{font-family:monospace,monospace;font-size:1em}a{background-color:transparent}abbr[title]{border-bottom:none;text-decoration:underline;text-decoration:underline dotted}b,strong{font-weight:bolder}code,kbd,samp{font-family:monospace,monospace;font-size:1em}small{font-size:80%}sub,sup{font-size:75%;line-height:0;position:relative;vertical-align:baseline}sub{bottom:-.25em}sup{top:-.5em}img{border-style:none}button,input,optgroup,select,textarea{font-family:inherit;font-size:100%;line-height:1.15;margin:0}button,input{overflow:visible}button,select{text-transform:none}button,[type=button],[type=reset],[type=submit]{-webkit-appearance:button}button::-moz-focus-inner,[type=button]::-moz-focus-inner,[type=reset]::-moz-focus-inner,[type=submit]::-moz-focus-inner{border-style:none;padding:0}button:-moz-focusring,[type=button]:-moz-focusring,[type=reset]:-moz-focusring,[type=submit]:-moz-focusring{outline:1px dotted ButtonText}fieldset{padding:.35em .75em .625em}legend{box-sizing:border-box;color:inherit;display:table;max-width:100%;padding:0;white-space:normal}progress{vertical-align:baseline}textarea{overflow:auto}[type=checkbox],[type=radio]{box-sizing:border-box;padding:0}[type=number]::-webkit-inner-spin-button,[type=number]::-webkit-outer-spin-button{height:auto}[type=search]{-webkit-appearance:textfield;outline-offset:-2px}[type=search]::-webkit-search-decoration{-webkit-appearance:none}::-webkit-file-upload-button{-webkit-appearance:button;font:inherit}details{display:block}summary{display:list-item}template{display:none}[hidden]{display:none}.chroma{color:#eee;background-color:#2c3e50}.chroma .err{color:#960050;background-color:#1e0010}.chroma .lntd{vertical-align:top;padding:0;margin:0;border:0}.chroma .lntable{border-spacing:0;padding:0;margin:0;border:0;width:auto;overflow:auto;display:block}.chroma .hl{display:block;width:100%;background-color:#ffc}.chroma .lnt{margin-right:.4em;padding:0 .4em}.chroma .ln{margin-right:.4em;padding:0 .4em}.chroma .k{color:#66d9ef}.chroma .kc{color:#66d9ef}.chroma .kd{color:#66d9ef}.chroma .kn{color:#f92672}.chroma .kp{color:#66d9ef}.chroma .kr{color:#66d9ef}.chroma .kt{color:#66d9ef}.chroma .na{color:#a6e22e}.chroma .nc{color:#a6e22e}.chroma .no{color:#66d9ef}.chroma .nd{color:#a6e22e}.chroma .ne{color:#a6e22e}.chroma .nf{color:#a6e22e}.chroma .nx{color:#a6e22e}.chroma .nt{color:#f92672}.chroma .l{color:#ae81ff}.chroma .ld{color:#e6db74}.chroma .s{color:#e6db74}.chroma .sa{color:#e6db74}.chroma .sb{color:#e6db74}.chroma .sc{color:#e6db74}.chroma .dl{color:#e6db74}.chroma .sd{color:#e6db74}.chroma .s2{color:#e6db74}.chroma .se{color:#ae81ff}.chroma .sh{color:#e6db74}.chroma .si{color:#e6db74}.chroma .sx{color:#e6db74}.chroma .sr{color:#e6db74}.chroma .s1{color:#e6db74}.chroma .ss{color:#e6db74}.chroma .m{color:#ae81ff}.chroma .mb{color:#ae81ff}.chroma .mf{color:#ae81ff}.chroma .mh{color:#ae81ff}.chroma .mi{color:#ae81ff}.chroma .il{color:#ae81ff}.chroma .mo{color:#ae81ff}.chroma .o{color:#f92672}.chroma .ow{color:#f92672}.chroma .c{color:#75715e}.chroma .ch{color:#75715e}.chroma .cm{color:#75715e}.chroma .c1{color:#75715e}.chroma .cs{color:#75715e}.chroma .cp{color:#75715e}.chroma .cpf{color:#75715e}.chroma .gd{color:#f92672}.chroma .ge{font-style:italic}.chroma .gi{color:#a6e22e}.chroma .gs{font-weight:700}.chroma .gu{color:#75715e}/*!* animate.css -https://daneden.github.io/animate.css/
* Version - 3.7.0
* Licensed under the MIT license - http://opensource.org/licenses/MIT
*
* Copyright (c) 2019 Daniel Eden*/@-webkit-keyframes flash{0%,50%,to{opacity:1}25%,75%{opacity:0}}@keyframes flash{0%,50%,to{opacity:1}25%,75%{opacity:0}}.flash{-webkit-animation-name:flash;animation-name:flash}@-webkit-keyframes bounceInRight{0%,60%,75%,90%,to{-webkit-animation-timing-function:cubic-bezier(0.215,0.61,0.355,1);animation-timing-function:cubic-bezier(0.215,0.61,0.355,1)}0%{opacity:0;-webkit-transform:translate3d(3000px,0,0);transform:translate3d(3000px,0,0)}60%{opacity:1;-webkit-transform:translate3d(-25px,0,0);transform:translate3d(-25px,0,0)}75%{-webkit-transform:translate3d(10px,0,0);transform:translate3d(10px,0,0)}90%{-webkit-transform:translate3d(-5px,0,0);transform:translate3d(-5px,0,0)}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}@keyframes bounceInRight{0%,60%,75%,90%,to{-webkit-animation-timing-function:cubic-bezier(0.215,0.61,0.355,1);animation-timing-function:cubic-bezier(0.215,0.61,0.355,1)}0%{opacity:0;-webkit-transform:translate3d(3000px,0,0);transform:translate3d(3000px,0,0)}60%{opacity:1;-webkit-transform:translate3d(-25px,0,0);transform:translate3d(-25px,0,0)}75%{-webkit-transform:translate3d(10px,0,0);transform:translate3d(10px,0,0)}90%{-webkit-transform:translate3d(-5px,0,0);transform:translate3d(-5px,0,0)}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}.bounceInRight{-webkit-animation-name:bounceInRight;animation-name:bounceInRight}@-webkit-keyframes bounceOutRight{20%{opacity:1;-webkit-transform:translate3d(-20px,0,0);transform:translate3d(-20px,0,0)}to{opacity:0;-webkit-transform:translate3d(2000px,0,0);transform:translate3d(2000px,0,0)}}@keyframes bounceOutRight{20%{opacity:1;-webkit-transform:translate3d(-20px,0,0);transform:translate3d(-20px,0,0)}to{opacity:0;-webkit-transform:translate3d(2000px,0,0);transform:translate3d(2000px,0,0)}}.bounceOutRight{-webkit-animation-name:bounceOutRight;animation-name:bounceOutRight}@-webkit-keyframes fadeIn{0%{opacity:0}to{opacity:1}}@keyframes fadeIn{0%{opacity:0}to{opacity:1}}.fadeIn{-webkit-animation-name:fadeIn;animation-name:fadeIn}@-webkit-keyframes slideInUp{0%{-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0);visibility:visible}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}@keyframes slideInUp{0%{-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0);visibility:visible}to{-webkit-transform:translateZ(0);transform:translateZ(0)}}.slideInUp{-webkit-animation-name:slideInUp;animation-name:slideInUp}@-webkit-keyframes slideOutDown{0%{-webkit-transform:translateZ(0);transform:translateZ(0)}to{visibility:hidden;-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0)}}@keyframes slideOutDown{0%{-webkit-transform:translateZ(0);transform:translateZ(0)}to{visibility:hidden;-webkit-transform:translate3d(0,100%,0);transform:translate3d(0,100%,0)}}.slideOutDown{-webkit-animation-name:slideOutDown;animation-name:slideOutDown}.animated{-webkit-animation-duration:1s;animation-duration:1s;-webkit-animation-fill-mode:both;animation-fill-mode:both}.animated.infinite{-webkit-animation-iteration-count:infinite;animation-iteration-count:infinite}.animated.delay-1s{-webkit-animation-delay:1s;animation-delay:1s}.animated.delay-2s{-webkit-animation-delay:2s;animation-delay:2s}.animated.delay-3s{-webkit-animation-delay:3s;animation-delay:3s}.animated.delay-4s{-webkit-animation-delay:4s;animation-delay:4s}.animated.delay-5s{-webkit-animation-delay:5s;animation-delay:5s}.animated.fast{-webkit-animation-duration:.8s;animation-duration:.8s}.animated.faster{-webkit-animation-duration:.5s;animation-duration:.5s}.animated.slow{-webkit-animation-duration:2s;animation-duration:2s}.animated.slower{-webkit-animation-duration:3s;animation-duration:3s}@media(prefers-reduced-motion),(print){.animated{-webkit-animation:unset!important;animation:unset!important;-webkit-transition:none!important;transition:none!important}}::-webkit-scrollbar{width:8px;height:8px;background:#2c3e50}::-webkit-scrollbar-thumb{background:#888}::-webkit-scrollbar-thumb:hover{background:#c6cddb}html{background:#494f5c;line-height:1.6;letter-spacing:.06em;scroll-behavior:smooth}body,button,input,select,textarea{color:#c6cddb;font-family:trebuchet ms,Verdana,verdana ref,segoe ui,Candara,lucida grande,lucida sans unicode,lucida sans,Tahoma,sans-serif}pre,code,pre tt{font-family:Consolas,andale mono wt,andale mono,Menlo,Monaco,lucida console,lucida sans typewriter,dejavu sans mono,bitstream vera sans mono,liberation mono,nimbus mono l,courier new,Courier,yahei consolas hybrid,monospace,segoe ui emoji,pingfang sc,microsoft yahei}pre{padding:.7em 1.1em;overflow:auto;font-size:.9em;line-height:1.5;letter-spacing:normal;white-space:pre;color:#eee;background:#2c3e50;border-radius:4px}pre code{padding:0;margin:0;background:#2c3e50}code{color:#eee;background:#7d828a;border-radius:3px;padding:0 3px;margin:0 4px;word-wrap:break-word;letter-spacing:normal}blockquote{border-left:.25em solid;margin:1em;padding:0 1em;font-style:italic}blockquote cite{font-weight:700;font-style:normal}blockquote cite::before{content:"—— "}a{color:#c6cddb;text-decoration:none;border:none;transition-property:color;transition-duration:.4s;transition-timing-function:ease-out}a:hover{color:#fff}hr{opacity:.2;border-width:0 0 5px;border-style:dashed;background:transparent;width:50%;margin:1.8em auto}table{border-collapse:collapse;border-spacing:0;empty-cells:show;width:100%;max-width:100%}table th,table td{padding:1.5%;border:1px solid}table th{font-weight:700;vertical-align:bottom}.section-inner{margin:0 auto;max-width:1200px;width:93%}.thin{max-width:720px;margin:auto}.feather{display:inline-block;vertical-align:-.125em;width:1em;height:1em}.desktop-only,.desktop-only-ib{display:none}.screen-reader-text{border:0;clip:rect(1px,1px,1px,1px);clip-path:inset(50%);height:1px;margin:-1px;overflow:hidden;padding:0;position:absolute!important;width:1px;word-wrap:normal!important}.screen-reader-text:focus{background-color:#f1f1f1;border-radius:3px;box-shadow:0 0 2px 2px rgba(0,0,0,.6);clip:auto!important;clip-path:none;color:#21759b;display:block;font-size:14px;font-size:.875rem;font-weight:700;height:auto;left:5px;line-height:normal;padding:15px 23px 14px;text-decoration:none;top:5px;width:auto;z-index:100000}#site-header{position:fixed;z-index:1;bottom:0;width:100%;box-sizing:border-box;box-shadow:-1px -2px 3px rgba(0,0,0,.45);background-color:#3b3e48}.hdr-wrapper{display:flex;justify-content:space-between;align-items:center;padding:.5em 0;font-size:1.2rem}.hdr-wrapper .site-branding{display:inline-block;margin-right:.8em;font-size:1.2em}.hdr-wrapper .site-nav{display:inline-block;font-size:1.1em;opacity:.8}.hdr-wrapper .site-nav a{margin-left:.8em}.hdr-icons{font-size:1.2em}.hdr-social{display:inline-block;margin-left:.6em}.hdr-social>a{margin-left:.4em}.hdr-btn{border:none;background:0 0;padding:0;margin-left:.4em;cursor:pointer}#menu-btn{display:none;margin-left:.6em;cursor:pointer}#mobile-menu{position:fixed;bottom:4.8em;right:1.5em;display:none;padding:.6em 1.8em;z-index:1;box-sizing:border-box;box-shadow:-1px -2px 3px 0 rgba(0,0,0,.45);background-color:#3b3e48}#mobile-menu ul{list-style:none;margin:0;padding:0;line-height:2;font-size:1.2em}#site-footer{text-align:center;font-size:.9em;margin-bottom:96px;margin-top:64px}#site-footer p{margin:0}#spotlight{display:flex;height:100vh;flex-direction:column;align-items:center;justify-content:center;max-width:93%;margin:auto;font-size:1.5rem}#spotlight.error-404{flex-direction:row;line-height:normal}p.img-404{margin:0}p.img-404 svg{width:180px;max-width:100%;height:auto}.banner-404{margin-left:2em}.banner-404 h1{font-size:3em;margin:.5rem 0}.banner-404 p{margin-top:0}.banner-404 .btn-404{font-size:.8em}.banner-404 .btn-404 a{display:inline-block;border:2px solid #c6cddb;border-radius:5px;padding:5px;transition-property:color,border-color}.banner-404 .btn-404 a:first-child{margin-right:1em}.banner-404 .btn-404 a:hover{border-color:#fff}.banner-404 .btn-404 a svg{margin-right:.5em}#home-center{display:flex;flex-grow:1;flex-direction:column;justify-content:center}#home-title{margin:0;text-align:center}#home-subtitle{margin-top:0;margin-bottom:1.5em;text-align:center;line-height:normal;font-size:.7em;font-style:italic;opacity:.9}#home-social{font-size:1.4em;text-align:center;opacity:.8}#home-social a{margin:0 .2em}#home-nav{opacity:.8}#home-nav a{display:block;text-align:center;margin-top:.5em}#home-footer{text-align:center;font-size:.6em;line-height:normal;opacity:.6}#home-footer p{margin-top:0}.posts-group{display:flex;margin-bottom:1.9em;line-height:normal}.posts-group .post-year{padding-top:6px;margin-right:1.8em;font-size:1.6em;opacity:.6}.posts-group .post-year:hover{text-decoration:underline;cursor:pointer}.posts-group .posts-list{flex-grow:1;margin:0;padding:0;list-style:none}.posts-group .post-item{border-bottom:1px #7d828a dashed}.posts-group .post-item a{display:flex;justify-content:space-between;align-items:baseline;padding:12px 0}.posts-group .post-day{flex-shrink:0;margin-left:1em;opacity:.6}.bg-img{width:100vw;height:100vh;opacity:.03;z-index:-1;position:fixed;top:0;background-attachment:fixed;background-repeat:no-repeat;background-size:cover;background-position:50%;transition:opacity .5s}.show-bg-img{z-index:100;opacity:1;cursor:pointer}.post-header{margin-top:1.2em;line-height:normal}.post-header .post-meta{font-size:.9em;letter-spacing:normal;opacity:.6}.post-header h1{margin-top:.1em}hr.post-end{width:50%;margin-top:1.6em;margin-bottom:.8em;margin-left:0;border-style:solid;border-bottom-width:4px}.content a{word-wrap:break-word;border:none;box-shadow:inset 0 -4px 0 #018574;transition-property:background-color}.content a:hover{background-color:#018574}.content figure{max-width:100%;height:auto;margin:0;text-align:center}.content figure p{font-size:.8em;font-style:italic;opacity:.6}.content figure.left{float:left;margin-right:1.5em;max-width:50%}.content figure.right{float:right;margin-left:1.5em;max-width:50%}.content figure.big{max-width:100vw}.content img{display:block;max-width:100%;height:auto;margin:auto;border-radius:4px}.content ul,.content ol{padding:0;margin-left:1.8em}.content a.anchor{float:left;margin-left:-20px;padding-right:6px;box-shadow:none;opacity:.8}.content a.anchor:hover{background:0 0;color:#018574;opacity:1}.content a.anchor svg{display:inline-block;width:14px;height:14px;vertical-align:baseline;visibility:hidden}.content a.anchor:focus svg{visibility:visible}.content h1:hover a.anchor svg,.content h2:hover a.anchor svg,.content h3:hover a.anchor svg,.content h4:hover a.anchor svg,.content h5:hover a.anchor svg,.content h6:hover a.anchor svg{visibility:visible}.footnotes{font-size:.85em}.footnotes a{box-shadow:none;text-decoration:underline;transition-property:color}.footnotes a:hover{background:transparent}.footnotes a.footnote-return{text-decoration:none}.footnotes ol{line-height:1.8}.footnote-ref a{box-shadow:none;text-decoration:none;padding:2px;border-radius:2px;background-color:#2c3e50}.post-info{font-size:.8rem;line-height:normal;opacity:.6}.post-info p{margin:.8em 0}.post-info a:hover{border-bottom:1px solid #018574}.post-info svg{margin-right:.8em}.post-info .tag{margin-right:.5em}.post-info .tag::before{content:"#"}#toc{position:fixed;left:50%;top:0;display:none}.toc-title{margin-left:1em;margin-bottom:.5em;font-size:.8em;font-weight:700}#TableOfContents{font-size:.8em;opacity:.6}#TableOfContents ul{padding-left:1em;margin:0}#TableOfContents>ul{list-style-type:none}#TableOfContents>ul ul ul{font-size:.9em}#TableOfContents a:hover{border-bottom:#018574 1px solid}.post-nav{display:flex;justify-content:space-between;margin-top:1.5em;margin-bottom:2.5em;font-size:1.2em}.post-nav a{flex-basis:50%;flex-grow:1}.post-nav .next-post{text-align:left;padding-right:5px}.post-nav .prev-post{text-align:right;padding-left:5px}.post-nav .post-nav-label{font-size:.8em;opacity:.8;text-transform:uppercase}@media(min-width:800px){.site-main{margin-top:3em}hr.post-end{width:40%}}@media(min-width:960px){.site-main{margin-top:6em}}@media(min-width:1300px){.site-main{margin-top:8em}.desktop-only,#toc.show-toc{display:block}.desktop-only-ib{display:inline-block}figure.left{margin-left:-240px}figure.left p{text-align:left}figure.right{margin-right:-240px}figure.right p{text-align:right}figure.big{width:1200px;margin-left:-240px}hr.post-end{width:30%}#toc{top:13em;margin-left:370px;max-width:220px}}@media(min-width:1800px){.site-main{margin-top:10em}.section-inner{max-width:1600px}.thin{max-width:960px}figure.left{max-width:75%;margin-left:-320px}figure.right{max-width:75%;margin-right:-320px}figure.big{width:1600px;margin-left:-320px}hr.post-end{width:30%}#toc{top:15em;margin-left:490px;max-width:300px}}@media(max-width:760px){.hide-in-mobile,.site-nav.hide-in-mobile{display:none}#menu-btn{display:inline-block}.posts-group{display:block}.posts-group .post-year{margin:-6px 0 4px}#spotlight.error-404{flex-direction:column;text-align:center}#spotlight.error-404 .banner-404{margin:0}}@media(max-width:520px){.content figure.left,.content figure.right{float:unset;max-width:100%;margin:0}hr.post-end{width:60%}#mobile-menu{right:1.2em}}

================================================
FILE: themes/hermit/resources/_gen/assets/scss/scss/style.scss_c16d144eee185fbddd582cd5e25a4fae.json
================================================
{"Target":"css/style.min.31706917653d2b9e8410abd431f30ec4359a88a94fc87a63654779d87329edec.css","MediaType":"text/css","Data":{"Integrity":"sha256-MXBpF2U9K56EEKvUMfMOxDWaiKlPyHpjZUd52HMp7ew="}}

================================================
FILE: themes/hermit/static/browserconfig.xml
================================================
<?xml version="1.0" encoding="utf-8"?>
<browserconfig>
    <msapplication>
        <tile>
            <square150x150logo src="/mstile-150x150.png"/>
            <TileColor>#00aba9</TileColor>
        </tile>
    </msapplication>
</browserconfig>


================================================
FILE: themes/hermit/static/site.webmanifest
================================================
{
    "name": "",
    "short_name": "",
    "icons": [
        {
            "src": "/android-chrome-192x192.png",
            "sizes": "192x192",
            "type": "image/png"
        },
        {
            "src": "/android-chrome-384x384.png",
            "sizes": "384x384",
            "type": "image/png"
        }
    ],
    "theme_color": "#ffffff",
    "background_color": "#ffffff",
    "display": "standalone"
}


================================================
FILE: themes/hermit/static/utteranc.js
================================================
parcelRequire=function(e){var r="function"==typeof parcelRequire&&parcelRequire,n="function"==typeof require&&require,i={};function u(e,u){if(e in i)return i[e];var t="function"==typeof parcelRequire&&parcelRequire;if(!u&&t)return t(e,!0);if(r)return r(e,!0);if(n&&"string"==typeof e)return n(e);var o=new Error("Cannot find module '"+e+"'");throw o.code="MODULE_NOT_FOUND",o}return u.register=function(e,r){i[e]=r},i=e(u),u.modules=i,u}(function (require) {var d={};function q(e){for(var r,o=/\+/g,n=/([^&=]+)=?([^&]*)/g,p=function(e){return decodeURIComponent(e.replace(o," "))},a={};r=n.exec(e);)a[p(r[1])]=p(r[2]);return a}function h(e){var r=[];for(var o in e)e.hasOwnProperty(o)&&r.push(encodeURIComponent(o)+"="+encodeURIComponent(e[o]));return r.join("&")}d.deparam=q,d.param=h;var a={};var g={},f="https://api.utteranc.es";g.UTTERANCES_API=f;var r=a&&a.__awaiter||function(e,t,r,n){return new(r||(r=Promise))(function(o,a){function i(e){try{l(n.next(e))}catch(t){a(t)}}function $(e){try{l(n.throw(e))}catch(t){a(t)}}function l(e){e.done?o(e.value):new r(function(t){t(e.value)}).then(i,$)}l((n=n.apply(e,t||[])).next())})},s=a&&a.__generator||function(e,t){var r,n,o,a,i={label:0,sent:function(){if(1&o[0])throw o[1];return o[1]},trys:[],ops:[]};return a={next:$(0),throw:$(1),return:$(2)},"function"==typeof Symbol&&(a[Symbol.iterator]=function(){return this}),a;function $(a){return function($){return function(a){if(r)throw new TypeError("Generator is already executing.");for(;i;)try{if(r=1,n&&(o=2&a[0]?n.return:a[0]?n.throw||((o=n.return)&&o.call(n),0):n.next)&&!(o=o.call(n,a[1])).done)return o;switch(n=0,o&&(a=[2&a[0],o.value]),a[0]){case 0:case 1:o=a;break;case 4:return i.label++,{value:a[1],done:!1};case 5:i.label++,n=a[1],a=[0];continue;case 7:a=i.ops.pop(),i.trys.pop();continue;default:if(!(o=(o=i.trys).length>0&&o[o.length-1])&&(6===a[0]||2===a[0])){i=0;continue}if(3===a[0]&&(!o||a[1]>o[0]&&a[1]<o[3])){i.label=a[1];break}if(6===a[0]&&i.label<o[1]){i.label=o[1],o=a;break}if(o&&i.label<o[2]){i.label=o[2],i.ops.push(a);break}o[2]&&i.ops.pop(),i.trys.pop();continue;}a=t.call(e,i)}catch($){a=[6,$],n=0}finally{r=o=0}if(5&a[0])throw a[1];return{value:a[0]?a[1]:void 0,done:!0}}([a,$])}}},j={value:null};function i(e){return f+"/authorize?"+h({redirect_uri:e})}function p(){return r(this,void 0,Promise,function(){var e,t,r;return s(this,function(n){switch(n.label){case 0:return e=f+"/token",[4,fetch(e,{method:"POST",mode:"cors",credentials:"include"})];case 1:return(t=n.sent()).ok?[4,t.json()]:[3,3];case 2:return r=n.sent(),j.value=r,[2,r];case 3:return[2,null];}})})}function v(e){addEventListener("click",function(t){if(t.target instanceof Element&&t.target.closest("[sign-in]")){t.preventDefault();parent.postMessage({type:"sign-in"},e)}})}a.token=j,a.getLoginUrl=i,a.loadToken=p,a.listenForSignIn=v;var b=document.currentScript;void 0===b&&(b=document.querySelector("script[src^=\"https://utteranc.es/client.js\"],script[src^=\"http://localhost:4000/client.js\"]"));for(var c={},e=0;e<b.attributes.length;e++){var k=b.attributes.item(e);c[k.name.replace(/^data-/,"")]=k.value}var l=document.querySelector("link[rel='canonical']");c.url=l?l.href:location.origin+location.pathname+location.search,c.origin=location.origin,c.pathname=location.pathname.length<2?"index":location.pathname.substr(1).replace(/\.\w+$/,""),c.title=document.title;var m=document.querySelector("meta[name='description']");c.description=m?m.content:"";var n=document.querySelector("meta[property='og:title'],meta[name='og:title']");c["og:title"]=n?n.content:"",document.head.insertAdjacentHTML("afterbegin","<style>\n    .utterances {\n      position: relative;\n      box-sizing: border-box;\n      width: 100%;\n      max-width: 760px;\n      margin-left: auto;\n      margin-right: auto;\n    }\n    .utterances-frame {\n      position: absolute;\n      left: 0;\n      right: 0;\n      width: 1px;\n      min-width: 100%;\n      max-width: 100%;\n      height: 100%;\n      border: 0;\n    }\n  </style>");var o=b.src.match(/^https:\/\/utteranc\.es|http:\/\/localhost:\d+/)[0],t=o+"/utterances.html";b.insertAdjacentHTML("afterend","<div class=\"utterances\">\n    <iframe class=\"utterances-frame\" title=\"Comments\" scrolling=\"no\" src=\""+t+"?"+h(c)+"\"></iframe>\n  </div>");var u=b.nextElementSibling;b.parentElement.removeChild(b),addEventListener("message",function(t){if(t.origin===o){var r=t.data;r&&"resize"===r.type&&r.height?u.style.height=r.height+"px":r&&"sign-in"===r.type&&(location.href=i(location.href))}});d.__esModule=true;a.__esModule=true;g.__esModule=true;return{"D53L":{},"ieWq":d,"5+Ph":a,"BYTq":g};});


================================================
FILE: themes/hermit/theme.toml
================================================
name = "Hermit"
license = "MIT"
licenselink = "https://github.com/Track3/hermit/blob/master/LICENSE"
description = "A minimal and fast hugo theme for bloggers."
homepage = "https://github.com/Track3/hermit"
tags = ["blog", "minimal", "dark", "responsive"]
features = [
  "single column",
  "featured image",
  "social icons",
  "google analytics",
  "disqus"
]
min_version = 0.43

[author]
  name = "Track3"
  homepage = "https://www.xxxlbox.com"