golang工程最佳实践_golang参考工程资源-CSDN文库

golang

需积分: 2 167 浏览量 2023-06-12 13:51:46 上传评论收藏 5.4MB PDF 举报

资源推荐

资源详情

资源评论

Go 工程化规范设计

首先理解工程化规范包括的两方面：

非编码类规范：开源规范，文档规范，版本规范，Git 规范，发布规范，…

编码类规范：目录规范，代码规范，接口规范，日志规范，错误码规范，…

开源规范

主流的开源许可证：

开源项目应遵循：

高单元覆盖率。可确保第三方开发者在开发完代码后，能很方便地对整个项目做详细的单元测试，也能保证提交代码的质

量。

要确保整个代码库和提交记录中，不能出现内部 IP、内部域名、密码、密钥这类信息。否则会造成敏感信息外漏，可能会对

内部业务造成安全隐患。

当开源项目被其他开发者提交 pull request、issue、comment 时要及时处理，可确保项目不断被更新，也可以激发其他开发

者贡献代码的积极性。

持续地更新功能和修复 Bug。对于已经结项、不维护的开源项目，需要及时地对项目进行归档，并在项目描述中加以说明。

…

文档规范

README 文档

README.md 用于介绍项目的功能、安装、部署、使用。

建议使用

readme.so 生成。

项目文档

要求易读和可快速定位目标内容，可提供中文与英文版本：

开发文档：描述项目开发流程，包括如何搭建开发环境、构建二进制文件、测试、部署等。

用户文档：软件的使用文档，对象一般是软件使用者。内容包括 API 文档、SDK 文档、安装文档、功能介绍文档、最佳实

践、操作指南、常见问题等。

参考目录结构：

docs

├── devel # 开发文档，可以提前规划好，英文版文档和中文版文档

│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构

│ └── zh-CN # 中文版文档，可以根据需要组织文件结构

│ └── development.md # 开发手册，可以说明如何编译、构建、运行项目

├── guide # 用户文档

│ ├── en-US/ # 英文版文档，可以根据需要组织文件结构

│ └── zh-CN # 中文版文档，可以根据需要组织文件结构

│ ├── api/ # API 文档

│ ├── best-practice # 最佳实践，存放一些比较重要的实践文章

│ │ └── authorization.md

│ ├── faq # 常见问题

│ │ ├── iam-apiserver

│ │ └── installation

│ ├── installation # 安装文档

│ │ └── installation.md

│ ├── introduction/ # 产品介绍文档

│ ├── operation-guide # 操作指南，可根据 RESTful 资源再划分为更细的子目录，存放系统功能操作手册

│ │ ├── policy.md

│ │ ├── secret.md

│ │ └── user.md

│ ├── quickstart # 快速入门

│ │ └── quickstart.md

│ ├── README.md # 用户文档入口文件

│ └── sdk # SDK 文档

│ └── golang.md

└── images # 图片存放目录

└── 部署架构v1.png

API 文档

一般由后端开发人员编写，描述组件提供的 API 以及调用方法。

可以编写 Word/Markdown 格式文档、借助工具编写（填充内容）、通过注释生成（如 Swagger）等。

通常需要包含完整的 API 接口介绍文档（接口描述、请求方法、请求参数、输出参数和请求示例）、API 接口变更历史文档、通

用说明、数据结构说明、错误码描述和 API 接口使用文档。

README.md ：API 接口介绍文档，会分类介绍 IAM 支持的 API 接口，并会存放相关 API 接口文档的链接，方便开发者查

看。

CHANGELOG.md ：API 接口文档变更历史，方便进行历史回溯，也可以使调用者决定是否进行功能更新和版本更新。

generic.md ：用来说明通用的请求参数、返回参数、认证方法和请求方法等。

struct.md ：用来列出接口文档中使用的数据结构。这些数据结构可能被多个 API 接口使用，会在 user.md、secret.md、

policy.md 文件中被引用。

user.md 、 secret.md 、 policy.md ：API 接口文档，相同 REST 资源的接口会存放在一个文件中，以 REST 资源名命名文

档名。

error_code.md ：错误码描述，通过程序自动生成。

其中接口描述：

主要参考极客时间《Go 语言项目开发实战》规范设计。

Go 工程化规范设计

Kyle's Notebook





CATALOG



1. Go 工程化规范设计

1.1. 开源规范

1.2. 文档规范

1.3. 版本规范

1.4. Git 规范

1.5. 目录结构

1.6. 编码规范

1.7. 代码测试

1.8. 性能分析

1.9. API 设计

1.10. 项目管理

1.11. 项目部署

1.12. 研发流程示例

1.13. 参考资料

接口描述：描述接口实现的功能。

请求方法：接口的请求方法，格式为 HTTP 方法请求路径，比如 POST /v1/users。在通用说明中的请求方法部分，会说

明接口的请求协议和请求地址。

输入参数：接口的输入字段，分为 Header 参数、Query 参数、Body 参数、Path 参数。每个字段通过：参数名称、必选、

类型和描述 4 个属性来描述。如果参数有限制或者默认值，可在描述部分注明。

输出参数：接口返回字段，每个字段通过参数名称、类型和描述 3 个属性来描述。

请求示例：真实的 API 接口请求和返回示例。

Swagger

使用 go-swagger 生成文档，可参考代码：

gopractise-demo/swagger 。

安装 swagger 命令行工具：

go get -u github.com/go-swagger/go-swagger/cmd/swagger

swagger version

# dev

在 Model 层代码中写上 Swagger 注释 sg/api/user.go：

// Package api defines the user model.

package api

// User represents body of User request and response.

type User struct {

// User's name.

// Required: true

Name

string `json:"name"`

// User's nickname.

// Required: true

Nickname

string `json:"nickname"`

// User's address.

Address

string `json:"address"`

// User's email.

string `json:"email"`

}

编写带 go-swagger 注释的 API 文档 sg/docs/doc.go：

// Package docs awesome.

// Documentation of our awesome API.

// Schemes: http, https

// BasePath: /

// Version: 0.1.0

// Host: some-url.com

// Consumes:

// - application/json

// Produces:

// - application/json

// Security:

// - basic

// SecurityDefinitions:

// basic:

// type: basic

// swagger:meta

package docs

编写 API 定义文件 sg/docs/user.go ：

package docs

import (

"github.com/marmotedu/gopractise-demo/sg/api"

)

// swagger:route POST /users user createUserRequest

// Create a user in memory.

// responses:

// 200: createUserResponse

// default: errResponse

// swagger:route GET /users/{name} user getUserRequest

// Get a user from memory.

// responses:

// 200: getUserResponse

// default: errResponse

// swagger:parameters createUserRequest

type userParamsWrapper struct {

// This text will appear as description of your request body.

// in:body

Body api.User

}

// This text will appear as description of your request url path.

// swagger:parameters getUserRequest

type getUserParamsWrapper struct {

// in:path

Name

string `json:"name"`

}

// This text will appear as description of your response body.

// swagger:response createUserResponse

type createUserResponseWrapper struct {

// in:body

Body api.User

}

// This text will appear as description of your response body.

// swagger:response getUserResponse

type getUserResponseWrapper struct {

// in:body

Body api.User

}

// This text will appear as description of your error response body.

// swagger:response errResponse

type errResponseWrapper struct {

// Error code.

Code

int `json:"code"`

// Error message.

Message

string `json:"message"`

}

Go 工程化规范设计

Kyle's Notebook





CATALOG



1. Go 工程化规范设计

1.1. 开源规范

1.2. 文档规范

1.3. 版本规范

1.4. Git 规范

1.5. 目录结构

1.6. 编码规范

1.7. 代码测试

1.8. 性能分析

1.9. API 设计

1.10. 项目管理

1.11. 项目部署

1.12. 研发流程示例

1.13. 参考资料

在 main.go 文件中导入 docs 包，使 go-swagger 在递归解析 main 包的依赖时找到 docs 包，并解析包中的注释。

import (

// ...

// This line is necessary for go-swagger to find your docs!

"github.com/marmotedu/gopractise-demo/sg/docs"

)

生成 Swagger API 文档，并启动 HTTP 服务，在浏览器查看 Swagger：

swagger generate spec -o swagger.yaml

swagger serve --no-open -F=redoc --port 36666 swagger.yaml

也可以生成 JSON 格式的 Swagger 文档：

swagger generate spec -i ./swagger.yaml -o ./swagger.json

其它功能可参考： Swagger 2.0 。

版本规范

一般使用语义化版本规范（SemVer，Semantic Versioning），即主版本号.次版本号.修订号（X.Y.Z，其中 X、Y 和 Z 为非负

的整数，且禁止在数字前方补零）。

也有先行版本号与编译版本号

v1.2.3-aplha.1+001 ：即把先行版本号（Pre-release）和版本编译元数据，作为延伸加到了主

版本号.次版本号.修订号的后面：

X.Y.Z[-先行版本号][+版本编译元数据] 。

主版本号（MAJOR）：不兼容的 API 修改。

必须在有任何不兼容的修改被加入公共 API 时递增。其中可以包括次版本号及修订级别的改变。每当主版本号递增

时，次版本号和修订号必须归零。

主版本号为零（0.y.z）的软件处于开发初始阶段，由于一切都可能随时被改变，不应该被视为稳定版。 1.0.0 被界

定为第一个稳定版本，之后的所有版本号更新都基于该版本修改。

次版本号（MINOR）：向下兼容的功能性新增及修改。一般偶数为稳定版本，奇数为开发版本。在任何公共 API 功能被标记

为弃用时也必须递增，当有改进时也可以递增。其中可以包括修订级别的改变。每当次版本号递增时，修订号必须归零。

修订号（PATCH）：向下兼容的问题修正，即 bug 修复。

先行版本号：该版本不稳定，可能存在兼容性问题。

编译版本号：编译器在编译过程中自动生成，开发者只定义其格式、不进行人为控制。

使用建议：

使用 0.1.0 作为首个开发版本号，在后续每次发行时递增次版本号。

稳定版本并第一次对外发布时版本号可定为 1.0.0。

严格按照 Angular commit message 规范提交代码时：

fix 类型的 commit 可将修订号 +1。

feat 类型的 commit 可将次版本号 +1。

带 BREAKING CHANGE 的 commit 可将主版本号 +1。

自动生成

IAM 项目采用 gsemver 自动生成版本号，参考 iam/ensure_tag.sh 。

Makefile 和 Shell 脚本用到的所有版本号使用

iam/common.mk 中的 VERSION 变量。

Git

规范

Commit 规范

常见的开源社区 commit message 规范：

比如 Angular 规范：

语义化：commit message 被归为有意义的类型用来说明本次 commit 的类型。

规范化：commit message 遵循预先定义好的规范，比如格式固定、都属于某个类型，可被开发者和工具识别。

基本格式：

<type>[optional scope]: <description>

空行

[

optional body]

空行

[

optional footer(s)]

建议使用 git commit 时不要使用 -m 选项，而 -a 进入交互界面编辑 commit message。

Header

只有一行，包括：type（必选）、scope（可选）和 subject（必选）。

type 分为：

Development：一般是项目管理类的变更，不会影响最终用户和生产环境的代码，比如 CI 流程、构建方式等的修改。通常可

以免测发布。

Production：会影响最终的用户和生产环境的代码。一定要慎重并在提交前做好充分的测试。

VERSION := $(shell git describe --tags --always --match='v*')

执行

git describe

时，符合条件的

tag

指向最新提交，则只显示

tag

的名字，否则会有相关的后缀描述该

tag

后有多少次提交，以

# 3

：表示自打

tag v1.0.0

以来有

次提交。

# g1909e47

：

为

git

的缩写，在多种管理工具并存的环境中很有用处。

# 1909e47

：

位字符表示为最新提交的

commit id

前

位。

Go 工程化规范设计

Kyle's Notebook





CATALOG



1. Go 工程化规范设计

1.1. 开源规范

1.2. 文档规范

1.3. 版本规范

1.4. Git 规范

1.5. 目录结构

1.6. 编码规范

1.7. 代码测试

1.8. 性能分析

1.9. API 设计

1.10. 项目管理

1.11. 项目部署

1.12. 研发流程示例

1.13. 参考资料

scope 说明 commit 影响范围，必须是名词，因项目而异。

初期可设置粒度较大的 scope（如按组件名或功能设置），后续项目有变动或有新功能时可添加新的 scope。

不适合设置太具体的值。会导致项目有太多的 scope 难以维护，开发者也难以确定 commit 所属的 scope 导致错放，反而失

去分类的意义。

subject 是 commit 的简短描述，明确指出 commit 执行的操作，以动词开头（小写）、使用现在时，不加句号。

Body

可分成多行，格式较自由。以动词开头、使用现在时。

必须包括修改的动机、跟上一版本相比的改动点。

Footer

根据需要选择，一般格式：

BREAKING CHANGE: <breaking change summary>

// 空行

// 空行

Fixes

#<issue number>

可说明本次 commit 导致的后果。

不兼容的改动：如当前代码跟上一个版本不兼容，需要在 Footer 部分以 BREAKING CHANG: 开头，跟上不兼容改动的摘要。其

他部分需要说明变动的描述、变动的理由和迁移方法：

BREAKING CHANGE: isolate scope bindings definition has changed and

the inject option for the directive controller injection was removed.

To migrate the code follow the example below:

Before:

scope: {

myAttr: 'attribute',

}

After:

scope: {

myAttr: '@',

}

The removed `inject` wasn't generaly useful for directives so there should be no code using it.

关闭的 Issue 列表：关闭的 Bug 需要在 Footer 部分新建一行，并以 Closes 开头列出，比如： Closes #123 。如果关闭多个

Issue，可以列出：

Closes #123, #432, #886 。

Change pause version value to a constant for image

Closes

#1137

Revert Commit

如果当前 commit 还原了先前的 commit，则应以 revert: 开头，后跟还原的 commit 的 Header。而且，在 Body 中必须写成

This

reverts commit <hash> ，其中 hash 是要还原的 commit 的 SHA 标识。

revert: feat(iam-apiserver): add 'Host' option

This reverts commit 079360c7cfc830ea8a6e13f4c8b8114febc9b48a.

管理 Commit

在对项目进行修改，通过测试（修复 bug、完成 feature）后立即 commit；或约定一个提交的周期，减少本地代码丢失造成的代码

丢失量。要避免 commit 太多，可在合并代码或提交 PR 时使用

git rebase -i 合并之前所有提交：建议把新的 commit 合并

到主干时只保留 2~3 个 commit 记录。

使用

git rebase -i commitId 进入交互界面，可列出该 commitId 之后的所有 commit。其支持的操作（默认是 pick）：

The body is mandatory for all commits except for those of scope "docs". When the body is required it must be at

Go 工程化规范设计

Kyle's Notebook





CATALOG



1. Go 工程化规范设计

1.1. 开源规范

1.2. 文档规范

1.3. 版本规范

1.4. Git 规范

1.5. 目录结构

1.6. 编码规范

1.7. 代码测试

1.8. 性能分析

1.9. API 设计

1.10. 项目管理

1.11. 项目部署

1.12. 研发流程示例

1.13. 参考资料

其中 squash 和 fixup 可用于合并 commit（注意是处理 commitId 和 HEAD 之间的 commit，开区间）。比如临时切换到 feature

分支进行开发：

git log --oneline

# 7157e9e docs(docs): append test line 'update3' to README.md

# 5a26aa2 docs(docs): append test line 'update2' to README.md

# 55892fa docs(docs): append test line 'update1' to README.md

# 89651d4 docs(doc): add README.md

# ========== feature/user 开发... ==========

git log --oneline

# 4ee51d6 docs(user): update user/README.md

# 176ba5d docs(user): update user/README.md

# 5e829f8 docs(user): add README.md for user

# f40929f feat(user): add delete user function

# fc70a21 feat(user): add create user function

# 以上是切换到 feature/user 分支进行开发后提交的 commit。

# 7157e9e docs(docs): append test line 'update3' to README.md

# 5a26aa2 docs(docs): append test line 'update2' to README.md

# 55892fa docs(docs): append test line 'update1' to README.md

# 89651d4 docs(doc): add README.md

在 feature 分支上的 5 个 commit 要在合并到 master 分支前进行精简，可选取切换 feature 分支前的最后一个 commit 进行 rebase

（比如 squash 操作）。最终 pick 前的四个 commit 都会被删除。

git rebase -i 7157e9e

# pick 4ee51d6 docs(user): update user/README.md

# s 176ba5d docs(user): update user/README.md

# s 5e829f8 docs(user): add README.md for user

# s f40929f feat(user): add delete user function

# s fc70a21 feat(user): add create user function

# Rebase 7157e9e..4ee51d6 onto 7157e9e (5 commands(s))

git log --oneline

# d6b17e0 feat(user): add user module with all function implements

# 7157e9e docs(docs): append test line 'update3' to README.md

# 5a26aa2 docs(docs): append test line 'update2' to README.md

# 55892fa docs(docs): append test line 'update1' to README.md

# 89651d4 docs(doc): add README.md

除此之外，如果有太多 commit 需要合并，可以先撤销过去的 commit，再创建一个新的（需要重新整理 commit message）：

git reset HEAD~3

git add .

git commit -am "feat(user): add user resource"

修改 Commit

修改最近提交的 commit：

git log --oneline

git commit --amend

修改某次 commit：

git rebase -i previousCommitId

第二种会导致父 commit 之后所有 commit 的 commitId。可能需要 git stash 将当前分支工作状态暂存，修改完成后再进行

git stash pop 恢复。

分支管理

集中式

所有开发者直接在 master 分支上工作。

功能分支

在开发新功能时基于 master 分支新建一个功能分支，在功能分支上进行开发，完成之后合并到 master 分支。

# 新建功能分支

git checkout -b feature/rate-limiting

# 开发工作提交到功能分支

git add limit.go

git commit -m "add rate limiting"

# 将本地功能分支代码 push 到远程仓库

Go 工程化规范设计

Kyle's Notebook





CATALOG



1. Go 工程化规范设计

1.1. 开源规范

1.2. 文档规范

1.3. 版本规范

1.4. Git 规范

1.5. 目录结构

1.6. 编码规范

1.7. 代码测试

1.8. 性能分析

1.9. API 设计

1.10. 项目管理

1.11. 项目部署

1.12. 研发流程示例

1.13. 参考资料

剩余28页未读，继续阅读

评论收藏

内容反馈

看_窗外

粉丝: 7
资源: 14

golang工程最佳实践

最佳实践：Codeship Golang最佳实践

golang-docker-jenkins:使用Docker和Jenkins最佳实践的示例Go应用程序项目

leetcode下载-best-practise:golang各种组件的最佳实践，持续更新

go-bank：开发用于简单银行应用程序的后端系统，用作围绕基于golang的API，带有SQLC的GORM和PostgresSQL作为数据库开发和使用的最佳实践的样板

百度APP之Golang语言实践

《8小时转职Golang工程师-语法部分》1

《Docker生态中的golang现状与实践》DaoCloud孙宏亮

Golang工程师-云客.htm

基于Golang语言结合领域驱动设计（DDD) 实现o2o业务模型项目源码

花椒直播基于golang的中台技术实践19.9 .pdf

golang中文手册_golang中文手册_goapiCHM_golang中文手册.chm_

Go语言学习之认识Golang

golang开发的软件license单机版工具

Golang在京东列表页实践总结.pdf

golang中文手册.rar

2.8 知乎社区核心业务 Golang 化实践 - 杜旭.pdf

golang解析数字证书

Centos7安装golang

golang-odbc 驱动

Golang 1.18.10 Windows安装包

黑群晖 ARPL 引导文件

ECharts+html大数据可视化大屏展示模板.zip

keil5 安装包

Axure9上最好用的组件库，自己一直再用的，强烈推荐

国军标软件开发文档要求（GJB438B-2009）

MATLAB安装MinGW-w64 C/C++编译器

TOGAF 9.2 中文（正式版）.pdf

群晖DS918+官网系统

最新资源