用最少的钱，实现工程效率实践

介绍

研发团队的工程效率实践，现在越来越多的人开始谈论这个话题，但是真真能实操的还本场 Chat 侧重于实践，不会有抽象的概念和理论知识。

我会拟一个场景来实战-《如何通过Gitlab+七牛云存储来构建在线产品需求文档》，一步一步的带领大家构建属于你自己或者你们团队的工程效率实践。

了解 Axure 产品原型工具

RP 是一个专业的快速原型设计工具。Axure（发音：Ack-sure），代表美国 Axure 公司；RP 则是 Rapid Prototyping（快速原型）的缩写。

Axure RP 是美国 Axure Software Solution 公司旗舰产品，是一个专业的快速原型设计工具，让负责定义需求和规格、设计功能和界面的专家能够快速创建应用软件或 Web 网站的线框图、流程图、原型和规格说明文档。

作为专业的原型设计工具，它能快速、高效的创建原型，同时支持多人协作设计和版本控制管理。

Axure RP 的使用者主要包括商业分析师、信息架构师、产品经理、IT 咨询师、用户体验设计师、交互设计师、UI 设计师等，另外，架构师、程序员也在使用 Axure。

摘自百度百科：

Axure 是一个极其简单的软件，如果你不需要做交互，那么你不看教程，也只要 10 分钟就可以掌握个大概。因为你所做的就是拖部件，打字，拖部件，打字，最多加个对齐。

了解 Gitlab Webhook

Webhook 是什么？：

Webhooks 是“用户定义的 HTTP 回调”，它们通常由一些事件触发，例如将代码推送到仓库或一个博客的评论。 发生该事件时，源应用程序将向 webhook 配置的 URI 发出一个 HTTP 请求，这个请求可以做任何事情。通常是用于触发构建持续集成系统，或者去通知错误跟踪系统。-维基百科

了解七牛云存储

首先，我们要进行七牛云账户注册，在个人账户和企业账户中选择一个，按照你自己的实际情况来选择就好了。

• 实名认证后可以享受到更多免费福利；
• 个人用户可以升级为企业用户，但企业用户不能降级为个人用户；

注册和实名认证都很简单，这里就不做介绍了。如果大家在注册过程中遇到了问题，请在读者圈中给我留言。

重点：对于认证用户，七牛云存储提供免费的存储空间 10GB，每月下载流量 10GB，每月 PUT/DELETE 10 万次请求，每月 GET 100 万次请求。

咱们即将要做的在线产品需求文档就是基于七牛云存储来对外发布的，对于个人来说免费 10GB 的存储空间足够了。

如何设计一个工程效率实践的产品

场景回顾

研发团队里面产品和开发的对接方式无外乎以下几种：

1. 原型图/交互图+prd（需求文档描述）；
2. Gitlab + Markdown（编写的prd+原型图）；
3. 禅道的需求管理：prd+原型图；
4. Axure 做的产品需求文档，导出html页面 熟悉 Axure 的人可能会说，Axure 就可以生成在线预览地址的，但是由于众所周知的原因，这个地址可能你无法访问；
5. Axure（HTML） + Gitlab（版本管理以及自动化流程）的在线需求文档；

以上是我们的一些尝试，不知道大家是哪一种呢？如果你们有其他更好的方式，还请大家留言，目前我们使用的是第 5 种。

在正式开始之前，我把产品经理的基本流程概述一下（有一些环节我隐掉了）：

1. 首先，产品经理撰写需求文档（可能采用的工具：word， markdown，axure，禅道，墨刀等）；
2. 产品将需求文档发给开发（方式：直接给文件，svn/git 上传，共享文件等）；
3. 产品变更需求，重新再发送（可能发生多次）；

从上面的流程中，我们可以看出产品人员需要做很多的沟通和操作，一点都不高效。

每一次变更你都必须重新更新上传，然后通知每个人。

针对以上场景的优化版本

• 产品经理撰写需求文档
• 提交到 Gitlab
• 触发 Gitlab Webhook
• pg：生成在线需求文档【包括：拉取需求文档到服务器使用 qshell 上传需求文档到七牛云得到在线需求文档地址 URL】
• 通过钉钉/Slack 机器人通知相关人。

整个过程中，产品经理只需要做一件事：撰写需求文档，其他所有的工作都自动化了（这就是我们的工程效率实践）。

说了那么多，咱们进入正题吧！

构建产品需求在线文档

目标

1. 快速将 HTML 页面生成一个可预览的在线地址；
2. HTML 页面也需要版本管理（Gitlab, Github, Coding, 码云等）；

• 每一次改动都有迹可循，别以为你偷偷改产品文档我们就不知道了；

1. 基于钉钉/Slack 机器人能够及时同步新增和变更；

在线地址规则

1. 七牛云存储 CDN 分发会给每一个空间分配一个域名 http://xxx.bkt.clouddn.com；
2. 文件格式： http://xxx.bkt.clouddn.com/pg_v1.0/index.html，实际对照 Gitlab ：https://xxx.gitlab.com/pg_group/pg_project/pg_v1.0/index.html；
3. 自定义域名（七牛云分配的域名可以备自定义为自己的域名-DNS 配置域名解析）；

项目结构

  ├── pg_group
  │----├── pg_project1
  │----│----├── pg_v1.0  
  │----│----├── pg_v1.1  
  │----│----└── pg_v2.0  
  │----└── pg_project2

详细操作步骤

新增产品需求文档

1. 登录进入 Gitlab 网站（可以是自建 Gitlab，Github，Coding，码云等）；
2. 点击 New Group (https://xxx.gitlab.com/groups/new)，填写 pg_group 信息，点击创建即可；
3. 点击 New Project (https://xxx.gitlab.com/projects/new) ，选择 pg_group ，然后填写：pg_project和基本描述，点击创建即可；
4. 进入 pg_project 项目；
5. 点击 Settings->Integrations ，配置该项目的 Webhook，在 URL 填写 https://ip:port/v1/webhook/process?dingAccessToken=xxxxxxx (此 token 为钉钉机器人的 token，如果不需要可以不加此参数)，在 Secret Token 填写 xxx，Trigger 勾选 Push events，点击 Add webhook 即可完成 Webhook 的添加；
6. git clone git@xxx.gitlab.com:pg_group/pg_project.git 到你本地~/develop/workspace/xxx.gitlab.com/pg_group/pg_project；
7. 在 pg_project 目录下创建产品需求版本目录 pg_v1.0；
8. 将 Axure 导出的 HTML 文件拷贝到 pg_project/pg_v1.0 目录；
9. 提交 pg_project 项目到 gitlab。
10. 触发 Webhook，执行自动化处理流程（这里不做阐述了）；

增加产品需求文档的小版本

1. 在 pg_project 目录下创建产品需求版本目录 pg_v1.1 或者 pg_v2.0 ；
2. 将 Axure 导出的 HTML 文件拷贝到 pg_project/pg_v1.1 目录；
3. 提交 pg_project 项目到 gitlab。
4. 触发 Webhook，执行自动化处理流程（这里不做阐述了）；

产品需求文档变更

1. 将 Axure 导出的 HTML 文件拷贝到 pg_project/pg_v1.0 目录；
2. 提交 pg_project 项目到 gitlab。
3. 触发 Webhook，执行自动化处理流程（这里不做阐述了）；

技术点

• Webhook 如何监听对应的变更（新增或者更新）；
• 上传七牛 CDN，如何封装 qshell 的调用；
• 钉钉机器人通知相关群组（推送信息包括：在线文档的 URL 地址）

核心代码

Gitlab Webhook PushEvents 推送的结构体：

// PushEvents 请求对应的实体
type PushEvents struct {
  After       string `json:"after"`
  Before      string `json:"before"`
  CheckoutSha string `json:"checkout_sha"`
  Commits     []struct {
    Added  []string `json:"added"`
    Author struct {
      Email string `json:"email"`
      Name  string `json:"name"`
    } `json:"author"`
    ID        string   `json:"id"`
    Message   string   `json:"message"`
    Modified  []string `json:"modified"`
    Removed   []string `json:"removed"`
    Timestamp string   `json:"timestamp"`
    URL       string   `json:"url"`
  } `json:"commits"`
  EventName  string `json:"event_name"`
  Message    string `json:"message"`
  ObjectKind string `json:"object_kind"`
  Project    struct {
    AvatarURL         string `json:"avatar_url"`
    CiConfigPath      string `json:"ci_config_path"`
    DefaultBranch     string `json:"default_branch"`
    Description       string `json:"description"`
    GitHTTPURL        string `json:"git_http_url"`
    GitSSHURL         string `json:"git_ssh_url"`
    Homepage          string `json:"homepage"`
    HTTPURL           string `json:"http_url"`
    Name              string `json:"name"`
    Namespace         string `json:"namespace"`
    PathWithNamespace string `json:"path_with_namespace"`
    SSHURL            string `json:"ssh_url"`
    URL               string `json:"url"`
    VisibilityLevel   int64  `json:"visibility_level"`
    WebURL            string `json:"web_url"`
  } `json:"project"`
  ProjectID  int64  `json:"project_id"`
  Ref        string `json:"ref"`
  Repository struct {
    Description     string `json:"description"`
    GitHTTPURL      string `json:"git_http_url"`
    GitSSHURL       string `json:"git_ssh_url"`
    Homepage        string `json:"homepage"`
    Name            string `json:"name"`
    URL             string `json:"url"`
    VisibilityLevel int64  `json:"visibility_level"`
  } `json:"repository"`
  TotalCommitsCount int64  `json:"total_commits_count"`
  UserAvatar        string `json:"user_avatar"`
  UserEmail         string `json:"user_email"`
  UserID            int64  `json:"user_id"`
  UserName          string `json:"user_name"`
  UserUsername      string `json:"user_username"`
}

// quploadRun 执行 qshell 的 qupload 命令，将产品文档的文件同步到七牛
func quploadRun(prdJSONPath string) error {
  cmd := exec.Command(cfg.QshellPath, "qupload", "4", prdJSONPath)
  _, err := cmd.CombinedOutput()
  return err
}

给你的产品赋予生命力

整合钉钉/Slack 等机器人

简单的机器人其实就是你给它指令，它去执行罢了。当我们的流程执行完成之后，发送一条消息到指定的钉钉讨论组（群）即可，还可以附加一些消息。

// SendDinghook 钉钉发送信息
func SendDinghook(dingAccessToken string, title string, content string) {
  ding := dinghook.Ding{AccessToken: dingAccessToken}
  markdown := dinghook.Markdown{Title: title, Content: content}
  ding.Send(markdown)
}

未来？

• 增加一个统一的产品需求展示页面（URL 链接需要增加时间戳鉴权处理，防止泄露）
• 增加一个可以方便配置 Webhook 的管理控制台；

遇到的问题/坑

• Open account file error, open ~/.qshell/account.json: no such file or directory, please use account to set AccessKey and SecretKey first

需要提前在你本地或者服务器上执行qshell account AccessKeyXxx SecretKeyXxx

参考资料

1. https://github.com/yangwenmai/pg
2. https://www.zhihu.com/question/19892861/answer/31059703
3. https://en.wikipedia.org/wiki/Webhook