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

1 编码规范

云端Poc目录结构:

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规范的信息标签

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

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

步骤规范演示:
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 编译规范

针对项目容器化方案实施的细节，容器化部署实施方案的部署实现，我们可以通过编写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 发布规范

发布规范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"]
可以指定相关的配置文件进行启动,目前系统针对配置文件启动加载的方式:

5 发布环境规范

5.1 测试环境

5.2 预发环境

5.3 生产环境

6 监控规范

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

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进行关联，实现监控数据接入到普罗米修斯中。