平台项目管理规范(Go语言版本)

1 编码规范

go版本	go1.13.4
开发环境	linux/mac/windows
git版本	2.7.3+
是否需要go fmt	需要
是否需要代码检查	需要
是否需要golint	需要
是否需要本地自测	需要
是否需要go mod tidy && go mod vendor	需要

平台目录结构:

apis	api接口文档(goSwagger)
APP-META	前端页面入口
bin	项目编译生成的二进制文件存放目录
configs	平台支持的模板配置模板
contrib	平台申请资源模板文件
daemon	平台的核心代码实现
docs	相关操作文档
hack	编译使用到的脚本文件
pkg	平台使用的公共方法
vendor	平台依赖存放的位置
Dockerfile	平台项目的容器化文件
Makefile	平台的编译文件
go.mod	平台模板根
go.sum	平台依赖包
main.go	平台的主函数入口
main_test.go	平台的单元测试

1.1 引包规范

项目开发过程中需要符合社区开发的项目规范标准:

import 系统包

换行

import 项目包

换行

import 第三方包

我们需要知道系统的建设，尤其云端Poc项目的开发实现需要完全符合社区的开发需求工作，在系统引包的流程中需要按照 系统包 项目包 第三方包进行导入，三种导包完成以后需要通过换行区分包的层次。

代码示例:

import (
    "strconv"
    "time"

    "gitlab.alibaba-inc.com/cloud-poc/poc-server/apis/types"
    "gitlab.alibaba-inc.com/cloud-poc/poc-server/daemon/config"
    "gitlab.alibaba-inc.com/cloud-poc/poc-server/daemon/mgr"
    "gitlab.alibaba-inc.com/cloud-poc/poc-server/pkg/metrics"

    "github.com/prometheus/client_golang/prometheus"
)

1.2 命名规范

1.1.1 结构体字段命名
首先判断结构体或者字段的使用范围，保持最小操作的命名规范标准，尽可能使用私有的变量和结构体以及方法实现函数功能的调用。

// deploymentMetrics is the deployment statistics metrics structure,
// the structure statistics deployment life cycle information.
type deploymentMetrics struct {
    // createDeploymentCount is system create deployment from db.
    createDeploymentCount *prometheus.CounterVec

    // existedDeploymentCount is system existe deployment count.
    existedDeploymentCount *prometheus.GaugeVec

    // deploymentDbCount is system create deployment from db.
    deploymentDbCount *prometheus.GaugeVec

    // deploymentApplyTime is system deployment apply time from db.
    deploymentApplyTime *prometheus.GaugeVec
}

首字母小写，避免引起安全调用的问题，声明全局私有的变量进行操作。

1.3 注释规范

查看代码注释文档信息（示例代码如下）:

1.3.1 函数代码规范标准
双斜杠+空格+函数名+函数解释+英文逗号结尾.

// checkoutDeploymentApplyTimeMetrics is used to count application deployment runing time.

注释说明:所有注释需要在注释字段或者方法的上方进行注解,所有注释都需要以函数名开头然后英文进行解释，需要一句简单明了的英文注释进行解释代码含义,最后以英文句号的形式结尾。

// checkoutDeploymentApplyTimeMetrics is used to count application deployment runing time.
func checkoutDeploymentApplyTimeMetrics(m *Manager) {
    deploymentQuery := m.deploymentApplyTimeArray()
    for _, v := range deploymentQuery {

1.3.2 结构体字段代码注释规范
注释在结构体上方:

双斜杠+空格+结构体名+英文注释内容+英文逗号结尾.

// deploymentStatistics is the deployment statistics structure.
type deploymentStatistics struct {
    Provider        string `json:"provider"`
    SoftwareName    string `json:"software_name"`
    SoftwareVersion string `json:"software_version"`
    SpecUID         string `json:"spec_uid"`
    Status          string `json:"status"`
    Count           int32  `json:"count"`
}

第二种注释，针对结构体中的某一字段进行注释(同上)

    // createDeploymentCount is system create deployment from db.
    createDeploymentCount *prometheus.CounterVec

1.4 Tag规范

如果配置出现多种的映射关系存在，比如需要映射到json或者yaml的字段映射,涉及到多种的数据结构体映射关系存在时，不同类别的映射字段通过空格区别。

// Config contains all configuration of daemon.
type Config struct {
    HomeDir       string                                `json:"homeDir" yaml:"homeDir"`
    ListenAddress string                                `json:"listen_address" yaml:"listen_address"`
    Debug         bool                                  `json:"debug" yaml:"debug"`
    SDConfig      *driver.Config                        `json:"sd" yaml:"sd"`
    DBConfig      *db.Config                            `json:"db" yaml:"db"`
    KMSConfig     *kms.KmsConfig                        `json:"kms" yaml:"kms"`
    SLSConfig     *sls.Config                           `json:"sls" yaml:"sls"`
    Infra         map[infra.InfraType]infra.InfraConfig `json:"infra" yaml:"infra"`
}

标准定义:

HomeDir       string                                `json:"homeDir" yaml:"homeDir"`

平台所有的代码文件和定义结构体涉及到的映射关系都需要参照如上的形式进行声明和使用。

2 代码提交规范

每次提交段代码需要符合代码提交规范:
每次提交，Commit message 都包括三个部分：
Header，Body 和 Footer。
其中，Header 是必需的，Body 和 Footer 可以省略。

Header部分只有一行，包括三个字段：

type（必需）、scope（可选）和subject（必需）。

云端Poc平台代码提交规范:feature: support max alive time config

2.1 commit规范的信息标签

feat	新功能（feature）
fix	修补bug
docs	文档（documentation）
style	格式（不影响代码运行的变动）
refactor	重构（即不是新增功能，也不是修改bug的代码变动）
test	增加测试
chore	构建过程或辅助工具的变动

代码提交需要合并的分支都需要满足符合要求,根据开头的标签类型区分提交分支的类型追加提交代码的功能，上述列表进行区分提交合并代码的功能和作用。

2.2 云端Poc平台代码提交流程规范

1 云端Poc平台项目代码
2 开发者拉取代码并切换到新的分支
3 代码合并提交测试
4 代码评审
5 代码修改/合并/提交测试
6 代码合入项目

步骤规范演示:
1 拉取项目代码

git clone http://gitlab.xxx-inc.com/cloud-xxx/xxx-server.git
// or 
git clone git@gitlab.xxx-inc.com:cloud-xxx/xxx-server.git

2 编辑/新增代码项目

// 根据代码功能选择自己的分支名(默认主分支develop)
git checkout -b software-update
// 代码新增或者编辑完成以后，需要提交更新后的代码文件(按照功能进行提交区分)
git add .
git commit -m "feat:update system software apply time"
git push origin software-update
// 同步合并最新分支到主分支
git commit -s --amend
git add .
git pull origin develop --rebase
git add .
git push -f origin software-update

3 提交代码评审合并请求
4 根据代码评审提出的相关问题进一步完善代码功能

// 代码评审，评审人会提示出相应的修改建议，代码需要进行变更操作
git add .
git commit -s --amend
git pull origin develop
git add .
git push -f origin software-update

第4步的操作需要反复进行执行，最终完成代码审核和并入云端Poc项目的实现中来，代码逻辑分支的并入或者新建需要按照最小单元的方式进行，即使最小的功能也需要按照新建分支进行标准提供。

3 编译规范

编译环境	golang1.13.4
编译工具	make(apk标准版)
配置文件支持类型	toml/yml/properties/props/prop/hcl(未验证)，json/yaml(已验证)
代码编译环境	golang:1.13.4-alpine
代码编译环境需要的依赖(apk安装)	apk add bash
	apk add make
代码编译环境更换国内源(加快编译速度)	sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories

针对项目容器化方案实施的细节，容器化部署实施方案的部署实现，我们可以通过编写Dockerfile对应用进行容器化改造措施，云端Poc的Dockerfile如下:

FROM golang:1.13.4-alpine as builderRUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositoriesRUN apk update && \    apk upgrade && \    apk add bash && \    apk add makeRUN mkdir -p /root/poc-server/COPY ./ /root/poc-server/RUN chmod 777 /root/poc-server/hack/*RUN cd /root/poc-server/ && CGO_ENABLED=0 make build

4 发布规范

基础镜像	alpine:3.8
国内镜像源	sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
代码编译环境需要的依赖(apk安装)	ca-certificates
	bash
	tzdata
配置文件变更	/etc/poc-server/config/config.json(支持多种变更文件)

发布规范Dockerfile:

FROM golang:1.13.4-alpine as builder

RUN sed -i 's/dl-cdn.alpinelinux.org/mirrors.aliyun.com/g' /etc/apk/repositories
RUN apk update && \
    apk upgrade && \
    apk add bash && \
    apk add make
RUN mkdir -p /root/xxx-server/
COPY ./ /root/xxx-server/
RUN chmod 777 /root/xxx-server/hack/*
RUN cd /root/poc-server/ && CGO_ENABLED=0 make build

配置文件说明:
Dockerfile中命令命令行:CMD ["--config","/etc/xxx-server/config/config.json"]
可以指定相关的配置文件进行启动,目前系统针对配置文件启动加载的方式:

默认配置文件	/etc/xxx-server/config.json
配置文件支持度
.json	支持
.yaml	支持
.yml	待验证
.toml	待验证
.properties	待验证
.props	待验证
.prop	待验证
.hcl	待验证

5 发布环境规范

5.1 测试环境

5.2 预发环境

5.3 生产环境

6 监控规范

平台监控的规范标准工作，涉及以下几个方面:
6.1 监控metrics信息暴露(云端Poc平台的metrics暴露)

环境	访问地址
云端Poc测试环境metrics	[http://test.xxx.com:8080/]
云端Poc生产环境	[http://pre.xxx-inc.com/]
云端Poc生产环境metrics	[http://product.xxx-inc.com/]

6.2 通过ServiceMonitor接入监控系统中
手动黑屏执行进行接入:

apiVersion: monitoring.coreos.com/v1
kind: ServiceMonitor
metadata:
  labels:
    app: poc-server
    release: ack-prometheus-operator
  name: poc-server
  namespace: monitoring
spec:
  endpoints:
  - path: /metrics
    port: tcp-8001
  namespaceSelector:
    matchNames:
    - cloudpoc-product
  selector:
    matchLabels:
      app: poc-server

需要结合发布的平台发布的服务名和相关的ingress进行关联，实现监控数据接入到普罗米修斯中。

本文由博客作者流雨声
github地址:https://github.com/vpc123

---