專案開發過程中的管理規範

流雨聲發表於2020-07-10

平臺專案管理規範(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

相關文章