Practice in Software Engineering

2023-11-28

软件工程团队实践（一）

如果不是已经有一段从业时间的软件工程师, 大概对软件工程的实践缺乏深切的感受。虽然如此, 我们每个人也都接触过软件工程领域的一些思想方法。
比如经典的《人月神话》这本书向我们展现了当软件团队开始扩大规模时, 会面临的种种问题。

本文是将会介绍一个 8 人的工程团队, 在实践中得到的收获。

软件工程团队实践（一）
- 团队介绍
- 管理工具
  - 接口管理
  - 开发管理

团队介绍

我并非专业的软件工程师, 工程团队的规模也只有 8 人, 构成如下.

职位	人数
产品经理	1
UI 设计师	1
前端工程师	1
后端工程师	2
深度学习工程师	1
电子工程师	1
结构工程师	1

团队的产品是通过传感器将采集到的信上传到服务器, 并且帮助用户对收集到的信息进行分析。
我自己是其中的一个后端工程师, 有幸能够从工程团队的角度分享一些思考和收获。

介绍分为三个部分

（一）管理工具
（二）设计思想
（三）团队协作

我的信念是如果问题可以通过技术手段解决就不必使用人为约定来规范, 这也是我先从工具开始介绍的原因, 他们都在开发过程中提供了巨大的方便。

管理工具

团队中每个人的工作都是相互依赖的, 硬件工程师和后端要协商传输规约, 后端给前端提供接口。
如何让使用我们功能的同事准确理解这些接口的功能, 是工程团队的沟通内容。

接口管理

在具体的开发写作中, 会遇到一些更加琐碎的问题, 例如

后端的接口已经更新了, 但是前端还在按照之前的版本进行开发
文档更新滞后, 数据库中的一些字段在文档里找不到解释

由于接口的功能会一直在变化, 所以功能滞后于实现的情况非常常见。而与其追求让接口文档跟上代码, 不如让接口本身就是代码。

Swagger

Swagger 的目标是把接口写在代码里。

以 Python 为例, 你可以直接把接口的定义写在 docstring 里。

from flask import request, jsonify

def delete_entity():
    '''删除某条记录
    delete entity
    ---
    tags:
        - machine
    parameters:
      - in: body
        name: params
        description: The entity to delete.
        schema:
            type: object
            required:
                - entity_id
                - user_id
                - user_name
                - jwt_token
            properties:
                entity_id:
                    type: integer
                    example: 1
                user_id:
                    type: integer
                    example: 1
                user_name:
                    type: string
                    example: admin
                jwt_token:
                    type: string
                    example: ***
    responses:
      200:
        description: entity delete succeed / fail
    '''
    if request.method == 'POST':
        proto = request.get_json()
        machine_id = proto.get('entity_id')

展现的效果如图所示

图1. Swagger

开发者可以提供一些例子以供使用者调试。

Hoppscotch

Swagger 其实仅仅能够针对接口给几个可用的样例, 但不是 Postman 的平替。更多针对接口的测试功能其实都不具备。Postman 虽然功能齐全, 想要进行团队协作却需要交不少钱, 对于我们这样的小团队来说, 为了节约成本把目光投向了开源方案 hoppscotch。

Hoppscotch 之前叫 PostWoman, 后来改成 hoppscotch。功能没那么全, 但是界面还是像模像样的, 私有化部署之后应该足够我们这样的小团队用了。

图2. Hoppscotchs

但是目前我还没有深度使用过 hoppscotchs, 过几个月再来补充更多的使用体验。

文档管理

项目文档太重要了, 比如数据库结构这些信息不得不用文档进行记录。
这部分内容没法直接写在函数注释里, 但是最好也和代码一起进行管理。

很多开源项目都采用这种方案(pytorch, flask, …)。
Pytorch 文档的页面最下方有 Built with Sphinx using a theme provided by Read the Docs. 的说明。

这也是我们试用之后觉得还算满意的方案, 即用 Sphinx 来写项目文档。

docs/
  |--source/:
  | |--conf.py
  | |--files ...
  |--build/:
  | |--html/:
  |   ...
  |--Makefile
source-code/:
  ...

文档的内容写在 /docs/source, 通过 sphinx 把源文档转为前端内容。
启动 sphinx 的服务也很简单。

1 2	sphinx-autobuild source build/html sphinx-autobuild source build/html --host $HOST --port $PORT

但是 sphinx 采用 reStructuredText 作为源文档的合适对我来说不太习惯。
尤其在画表格的时候, rST 要求每个单元的 char 个数一样, 但是中文算两个字符, 所以表格中有中文会写的很难受。
如果你实在写不来 rST 可以先写 markdown 然后用 cloudconvert 进行转换.

开发管理

环境管理

多人协同其实不是个小问题. 我们的项目不大, 需要配置的仅仅是

conda 环境 (flask, flaswagger 等工具)
mongodb, redis 等组件

但是合作者大约花了 3 天的时间完成了对环境的熟悉, 虽然很快了, 但是如果我把当前的运行环境做成了 docker 镜像, 完全有机会更快。

当然, 这样做也会有潜在的问题。因为在系统中, 没有哪个模块的功能是独立存在的, 而如果你所依赖的那个接口不可靠, 会产生很大的问题。这也是为什么越是底层的模块, 越要由那些经验丰富的程序员负责。

服务管理

对于很多共有的服务模块, 其实应该进行拆分, 如: 关系数据库(Mysql), 内存数据库(redis), 消息队列, 对象存储。

我目前用把他们都放在 docker 里面, 但是如果之后有更多服务会需要 K8S 这样的容器管理工具, 等我以后有所体会了再补充这个部分吧。

分支管理

多人协作大概率要用到 Git, 那么如何进行分支管理比较好呢.

GIT Server: 项目的多人合作是个问题, 只用 gitee 进行托管的话, 支持的协作人数太有限了.
至少应该搭建一个 Git 私服, 进一步的, 应该搭建自己的 gitlab 服务才对。搭建 Git 私服可以参考代码随想录的博客。

Gitea: 只搭建 git 服务器, 和别的协作者同步进度就很不方便, 比如想要像 Github 那样手动合并分支就很难完成。所以搭建一个 GitLab 服务器就很有必要。如果觉得 GitLab 的运行负担比较大, 还可以尝试 Gitea。比较轻量级而且完全开源, 能够满足基本的 Git 服务器功能。

当然, 最好是用 Docker 安装 Gitea: 参考 Install Gitea with Docker。如果觉得把所有的代码仓库都放在私服上不够保险, 可以使用 Gitea 的镜像仓库功能。
向 gitee/github 定期 pull/push, 这样来进行远程备份。

代码规范

多人合作的时候需要对代码风格进行约束, 这个利用 black 就可以做到。

这个功能应该集成到 Gitea 中。