Uber Go 语言编码规范中文版. The Uber Go Style Guide . .zip

<!-- Editing this document: - Discuss all changes in GitHub issues first. - Update the table of contents as new sections are added or removed. - Use tables for side-by-side code samples. See below. Code Samples: Use 2 spaces to indent. Horizontal real estate is important in side-by-side samples. For side-by-side code samples, use the following snippet. ~~~ <table> <thead><tr><th>Bad</th><th>Good</th></tr></thead> <tbody> <tr><td> ```go BAD CODE GOES HERE ``` </td><td> ```go GOOD CODE GOES HERE ``` </td></tr> </tbody></table> ~~~ (You need the empty lines between the <td> and code samples for it to be treated as Markdown.) If you need to add labels or descriptions below the code samples, add another row before the </tbody></table> line. ~~~ <tr> <td>DESCRIBE BAD CODE</td> <td>DESCRIBE GOOD CODE</td> </tr> ~~~ --> <!-- change.md # 2019-12-17 - 函数选项：推荐 “Option” 接口的结构实现 - 而不是用闭包捕获值。 # 2019-11-26 - 添加针对全局变量变异的指导。 # 2020-01-11 - 为`open（..）`调用添加缺少的参数。 # 2020-02-03 - 使用 `"time"` 处理时间的建议 - 添加有关在公共结构中嵌入类型的指导。 # 2020-02-25 - 添加有关接口验证是否符合编译时检查的指导。 # 2020-06-05 - 添加避免使用内置名称的指导意见 # 2020-06-10 - 添加 init() 指导意见 # 2020-06-16 - 追加时优先指定切片容量 - 添加有关指针接收器可调用性的说明 # 2020-06-17 - map 和切片的联合指导 # 2020-09-15 - Remove main panic # 2021-03-17 - 结构体初始化 # 2021-04-19 - 程序只能在`main()`中退出，最好最多退出一次 # 2021-11-16 - 添加有关将 `%w` 与 `%v` 与 `fmt.Errorf` 结合使用的指南，以及在何处使用 `errors.New` 或自定义错误类型。 # 2022-01-05 - 修复翻译错误 - 修复部分失效的链接 # 2022-03-30 - 添加有关在封送结构中使用字段标记的指导。 - # 2022-10-18 - 管理goroutine生命周期的指导. # 2023-04-13 - Errors: 只添加一次错误处理指南 --> ## [uber-go/guide](https://github.com/uber-go/guide) 的中文翻译 ## [English](https://github.com/uber-go/guide/blob/master/style.md) ## Uber Go 语言编码规范 [Uber](https://www.uber.com/) 是一家美国硅谷的科技公司，也是 Go 语言的早期 adopter。其开源了很多 golang 项目，诸如被 Gopher 圈熟知的 [zap](https://github.com/uber-go/zap)、[jaeger](https://github.com/jaegertracing/jaeger) 等。2018 年年末 Uber 将内部的 [Go 风格规范](https://github.com/uber-go/guide) 开源到 GitHub，经过一年的积累和更新，该规范已经初具规模，并受到广大 Gopher 的关注。本文是该规范的中文版本。本版本会根据原版实时更新。 ## 版本 - 当前更新版本：2022-04-25 版本地址：[commit:#207](https://github.com/uber-go/guide/commit/6faf78242fbb4c4296861eff65b6cfa274acaa87) - 如果您发现任何更新、问题或改进，请随时 fork 和 PR - Please feel free to fork and PR if you find any updates, issues or improvement. ## 目录 - [uber-go/guide 的中文翻译](#uber-goguide-的中文翻译) - [English](#english) - [Uber Go 语言编码规范](#uber-go-语言编码规范) - [版本](#版本) - [目录](#目录) - [介绍](#介绍) - [指导原则](#指导原则) - [指向 interface 的指针](#指向-interface-的指针) - [Interface 合理性验证](#interface-合理性验证) - [接收器 (receiver) 与接口](#接收器-receiver-与接口) - [零值 Mutex 是有效的](#零值-mutex-是有效的) - [在边界处拷贝 Slices 和 Maps](#在边界处拷贝-slices-和-maps) - [接收 Slices 和 Maps](#接收-slices-和-maps) - [返回 slices 或 maps](#返回-slices-或-maps) - [使用 defer 释放资源](#使用-defer-释放资源) - [Channel 的 size 要么是 1，要么是无缓冲的](#channel-的-size-要么是-1要么是无缓冲的) - [枚举从 1 开始](#枚举从-1-开始) - [使用 time 处理时间](#使用-time-处理时间) - [使用 `time.Time` 表达瞬时时间](#使用-timetime-表达瞬时时间) - [使用 `time.Duration` 表达时间段](#使用-timeduration-表达时间段) - [对外部系统使用 `time.Time` 和 `time.Duration`](#对外部系统使用-timetime-和-timeduration) - [Errors](#errors) - [错误类型](#错误类型) - [错误包装](#错误包装) - [错误命名](#错误命名) - [一次处理错误](#一次处理错误) - [处理断言失败](#处理断言失败) - [不要使用 panic](#不要使用-panic) - [使用 go.uber.org/atomic](#使用-gouberorgatomic) - [避免可变全局变量](#避免可变全局变量) - [避免在公共结构中嵌入类型](#避免在公共结构中嵌入类型) - [避免使用内置名称](#避免使用内置名称) - [避免使用 `init()`](#避免使用-init) - [追加时优先指定切片容量](#追加时优先指定切片容量) - [主函数退出方式 (Exit)](#主函数退出方式-exit) - [一次性退出](#一次性退出) - [在序列化结构中使用字段标记](#在序列化结构中使用字段标记) - [不要一劳永逸地使用 goroutine](#不要一劳永逸地使用-goroutine) - [等待 goroutines 退出](#等待-goroutines-退出) - [不要在 `init()` 使用 goroutines](#不要在-init-使用-goroutines) - [性能](#性能) - [优先使用 strconv 而不是 fmt](#优先使用-strconv-而不是-fmt) - [避免字符串到字节的转换](#避免字符串到字节的转换) - [指定容器容量](#指定容器容量) - [指定 Map 容量提示](#指定-map-容量提示) - [指定切片容量](#指定切片容量) - [规范](#规范) - [避免过长的行](#避免过长的行) - [一致性](#一致性) - [相似的声明放在一组](#相似的声明放在一组) - [import 分组](#import-分组) - [包名](#包名) - [函数名](#函数名) - [导入别名](#导入别名) - [函数分组与顺序](#函数分组与顺序) - [减少嵌套](#减少嵌套) - [不必要的 else](#不必要的-else) - [顶层变量声明](#顶层变量声明) - [对于未导出的顶层常量和变量，使用\_作为前缀](#对于未导出的顶层常量和变量使用_作为前缀) - [结构体中的嵌入](#结构体中的嵌入) - [本地变量声明](#本地变量声明) - [nil 是一个有效的 slice](#nil-是一个有效的-slice) - [缩小变量作用域](#缩小变量作用域) - [避免参数语义不明确 (Avoid Naked Parameters)](#避免参数语义不明确-avoid-naked-parameters) - [使用原始字符串字面值，避免转义](#使用原始字符串字面值避免转义) - [初始化结构体](#初始化结构体) - [使用字段名初始化结构](#使用字段名初始化结构) - [省略结构中的零值字段](#省略结构中的零值字段) - [对零值结构使用 `var`](#对零值结构使用-var) - [初始化 Struct 引用](#初始化-struct-引用) - [初始化 Maps](#初始化-maps) - [字符串 string format](#字符串-string-format) - [命名 Printf 样式的函数](#命名-printf-样式的函数) - [编程模式](#编程模式) - [表驱动测试](#表驱动测试) - [功能选项](#功能选项) - [Linting](#linting) - [Lint Runners](#lint-runners) - [Stargazers over time](#stargazers-over-time) ## 介绍 样式 (style) 是支配我们代码的惯例。术语`样式`有点用词不当，因为这些约定涵盖的范围不限于由 gofmt 替我们处理的源文件格式。 本指南的目的是通过详细描述在 Uber 编写 Go 代码的注意事项来管理这种复杂性。这些规则的存在是为了使代码库易于管理，同时仍然允许工程师更有效地使用 Go 语言功能。 该指南最初由 [Prashant Varanasi] 和 [Simon Newton] 编写，目的是使一些同事能快速使用 Go。多年来，该指南已