6.9 编码规范 #

Go规范 #

• Go官方规范： The Go Programming Language Specification Language version go1.24 (Dec 30, 2024)
  • 中文翻译： Go编程语言规范
  • Go官方 Code Review Comments:  https://github.com/golang/go/wiki/CodeReviewComments
  • Go官方的Effective Go:  https://go.dev/doc/effective_go
• Google Go Style： https://google.github.io/styleguide/go/ （2022.11.23年开始开源）
  • 中文翻译： https://gocn.github.io/styleguide/docs/04-best-practices/#关于
  • 中文翻译2： https://learnku.com/go/wikis/38426
• Uber Go Style Guide： https://github.com/uber-go/guide （2018年开始开源，业界认可度最高）
  • 中文翻译: https://github.com/xxjwxc/uber_go_guide_cn

protobuf规范 #

• protobuf style guide: https://protobuf.dev/programming-guides/style/

错误码规范 #

• MDN HTTP response status codes： HTTP 响应状态码 - HTTP | MDN

  1. 信息响应 (100–199)
  2. 成功响应 (200–299)
  3. 重定向消息 (300–399)
  4. 客户端错误响应 (400–499)
  5. 服务端错误响应 (500–599)

• 设计一套错误码的注意事项

  • 错误码结构：系统编码（区分不同的模块）+ 业务编码（如交易、商品管理、用户认证等）+错误类型编码（具体的错误描述，如数据校验错误、权限不足）+接口或操作编码
  • 错误码定义（如20001表示成功，50001表示服务器内部错误）、错误码文档、统一标准（如HTTP状态码保持一定程度的一致）
  • 可读性（code、msg）和扩展性

打印日志规范 #

• 结构化日志： https://github.com/hertz-contrib/logger 、klog
• 打印具体的问题和原因，以及其他关键信息（如UID）
• 打印traceid用于链路追踪
• 稳定打印日志（如不能把日志输出到没有写权限的文件，不能业务出bug日志也没打印）

commit规范 #

• 约定式提交规范： https://www.conventionalcommits.org/zh-hans/v1.0.0/

1
2
3
4
5

<type>[optional scope]: <description>   <类型>[可选 范围]: <描述>

[optional body]  [可选 正文]

[optional footer(s)]  [可选 脚注]

示例：包含了描述并且脚注中有破坏性变更的提交说明

1
2
3

feat: allow provided config object to extend other configs

BREAKING CHANGE: `extends` key in config file is now used for extending other config files

示例：包含了 **!** 字符以提醒注意破坏性变更的提交说明

1

feat!: send an email to the customer when a product is shipped

包含了范围和破坏性变更 **!** 的提交说明

1
2

feat(api)!: send an email to the customer when a product is shipped
**包含了 **`**!**`** 和 BREAKING CHANGE 脚注的提交说明**

1
2
3
4

chore!: drop support for Node 6

BREAKING CHANGE: use JavaScript features not available in Node 6.
**不包含正文的提交说明**

1

docs: correct spelling of CHANGELOG

包含范围的提交说明

1

feat(lang): add polish language

包含多行正文和多行脚注的提交说明

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

fix: prevent racing of requests

Introduce a request id and a reference to latest request. Dismiss
incoming responses other than from latest request.

Remove timeouts which were used to mitigate the racing issue but are
obsolete now.

Reviewed-by: Z
Refs: #123

• “必须（MUST）”、“禁止（MUST NOT）”、“必要（REQUIRED）”、“应当（SHALL）”、“不应当（SHALL NOT）”、“应该（SHOULD）”、“不应该（SHOULD NOT）”、“推荐（RECOMMENDED）”、“可以（MAY）” 和 “可选（OPTIONAL）”

语义化版本号规范 #

• 语义化版本： https://semver.org/lang/zh-CN/
• 版本格式：主版本号.次版本号.修订号，版本号递增规则如下：
  • 主版本号：当你做了不兼容的 API 修改，
  • 次版本号：当你做了向下兼容的功能性新增，
  • 修订号：当你做了向下兼容的问题修正。
• 语义化版本控制规范（SemVer）
  • 主版本号为零（0.y.z）的软件处于开发初始阶段，一切都可能随时被改变。这样的公共 API 不应该被视为稳定版
  • …