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

流雨聲發表於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

專案管理：規範化的過程及關鍵概念（轉）
2007-08-15
專案管理
專案開發過程管理(草稿)
2007-08-27
個人專案開發規範
2019-08-06
專案開發流程規範文件
2009-07-23
規範軟體開發過程——軟體配置管理實踐
2008-07-09
javascript專案開發規範例項
2017-12-05
JavaScript
專案管理過程中的知識管理初探（轉）
2007-08-10
專案管理
淺談專案的規範管理(轉)
2007-08-15
[原創]專案過程管理在專案管理中的重要性
2019-01-13
專案管理
專案中的 Git 使用規範
2020-04-09
Git
用制度規範專案管理（轉）
2007-08-13
專案管理
專案管理過程中的知識管理初探1（轉）
2007-08-10
專案管理
專案管理過程中的知識管理初探2（轉）
2007-08-10
專案管理
專案管理過程中的知識管理初探3（轉）
2007-08-10
專案管理
專案範圍管理各過程的輸入輸出關係
2015-03-03
團隊專案的Git分支管理規範
2019-06-18
Git
專案中的 Git 使用規範 [轉]
2020-04-09
Git
在開發過程中終止一個專案的想法
2014-11-18
NodeJs專案開發中應用ESLint程式碼規範
2021-09-09
NodeJSEsLint
研發中版本管理的規範性
2017-11-21
專案管理過程中的問題分析方法（轉）
2007-08-15
專案管理
2.1it專案的管理過程
2020-10-12
如何規範化專案管理，提升效率？
2021-02-03
專案管理
網站專案管理規範手冊
2009-01-12
網站專案管理
專案管理規範-RUP管理實施（三）(轉)
2007-08-14
專案管理
python大型專案開發規範_學習Python模組匯入機制與大型專案的規範
2021-02-10
Python
專案管理過程概述（轉）
2007-08-09
專案管理
專案管理過程中安全管理的一些體會（轉）
2007-08-16
專案管理
專案管理過程中的問題分析方法1（轉）
2007-08-09
專案管理
專案管理過程中的問題分析方法2（轉）
2007-08-09
專案管理
專案管理過程中的問題分析方法3（轉）
2007-08-09
專案管理
如何打造規範的開源專案workflow
2018-08-02
前端規範之vue 專案規範
2019-07-01
前端Vue
專案管理——遊戲開發中的成本管理
2019-01-14
專案管理遊戲開發
專案管理的五大過程
2020-06-24
專案管理
設工程專案管理規範問答（轉）
2007-08-10
專案管理
軟體專案管理（CMM）經驗談——附錄《產品部開發規範》
2010-10-13
專案管理
對規範施工企業專案管理的思考（轉）
2007-08-15
專案管理