跬步 On Coding

如何快速上手项目

Jan 8 2025

职业生涯中接手过很多项目了，各种项目都接触过，一个对新人友好的项目一般具备如下特征：

  1. 完备的安装/功能文档
  2. 完备的技术方案，架构设计文档
  3. 合理的分层，清晰的代码目录结构
  4. 可读，可维护性高的代码

但是往往我们会忽略一个一个简单的指引性的文档：Quick Start，这个文档不需要很详细，只需要说明，如何快速上手的过程，具体的步骤链接到对应的文档即可。一般我们会在Quick Start上写明：

  1. 最简安装的步骤
  2. 主流程功能的使用
  3. 开发环境的搭建
  4. 开发注意事项
    1. 包含组件的架构图
    2. 包含代码的分层目录说明

这个文档需要由项目的负责人编写，在后续由项目的新人实践的过程中逐步完善。

当然这都是比较理想的情况，实际情况中，我们可能遇到的项目可能根本就没有文档，然后只有一个代码仓库的情况，那怎么才能快速上手呢？其实还是按照Quick Start的思路，只不过需要自己来摸索来了。

1. 安装

我相信不管什么项目，或多或少都有一些如何安装的文档，如果连一点这样的文档都没有，那就需要问其它同事了，如果连问都问不出来，那恭喜你赶快跑路吧，😂

因为我们是初次接触项目，不必搞懂安装的每个步骤，每个配置的含义，目标仅仅是把项目跑起来，能用起来，所以这里的目标就是安装最简化的方式把项目跑起来。当前的后端项目一般采用容器交付的形式，一般就交付镜像与helm chart，这种方式的安装理论来说是非常简单的，一条helm install 的命令就可以搞定。所以我们在交付的的时一定要在默认的配置中写好最简化的配置，这样新人就可以直接用默认的配置来安装。

2. 功能体验

安装好之后，我们就可以从产品的角度开始体验项目的相关功能，这里我们要聚焦到项目的核心功能上，跑完整个主要流程，不要在意细节，也不要急于把体验的功能与代码实现结合起来，我们只要梳理功能流程，数据的流转，数据的建模。然后有经验的程序员往往会在这个过程中思考，这个功能如果是我来做，我会怎么做。在这个过程中一定要有自己的输出，比如：

  1. 功能清单
  2. 功能流程图
  3. 数据模型
  4. 数据流转图

如果有思考如何实现，还可以记录这些：

  1. 技术选型
  2. 技术方案
  3. 架构设计

在体验过程中如果发现了问题，也需要记录下来，还有自己对项目的疑问，为什么要这么设计，这个功能解决的什么实际问题等等。

但是我们需要注意的是避免陷入细节，有些东西没搞懂就没搞懂，没有关系，我们是一个新人，搞不懂也正常，把没搞懂的问题记录下来，后续再逐步熟悉。

3. 组件拆解与用途分析

在功能体验完成后，我们就有了自己的对与项目的思考，也有了一些疑问，然后我们就可以从项目的依赖的各个组件来逐步搞清楚这些问题。比如项目中用了什么数据库，用了什么缓存等等。然后我们可以对照我们自己的分析来看看项目是不是真的就是想我们想想的来实现的，数据库的表设计是不是也跟我们的数据建模一致。经验丰富的程序员往往很快就能猜出项目的主要组件依赖，快速画出一个简单的架构图。

4. 项目代码分析

搞明白各个组件的用途后，我们需要的是单刀直入，从主要功能流程出发，找到对应代码的入口，然后按照我们整理的功能流程，梳理出代码流转的过程，在这个过程中我们就可以大体分析出项目代码中目录的分层，各个模块的功能了。我们还可以借助工具来绘制代码的依赖图，这样可以帮助我们快速的理解代码。

在阅读的过程中代码本身可能也会有我们看不惯的地方，这个时候我们需要把代码切出一个分支来，专门用来记录自己阅读时写的注释以及一些觉得要重构的点，但是千万不要直接开始动手，一定只是记录，打上标记，比如：

// TODO: 这里有待重构
// ? 为什么这里用的是这种方式

等等，也是把自己的疑问记录下来，后续有需要可以带着疑问去问同事。

在代码阅读的过程中，切记不要陷入细节，不要陷入细节，不要陷入细节。我们只需要搞清楚代码流转的过程即可，至于代码的实现细节，我们后续在解BUG的过程中再去逐步熟悉。

5. 从小问题入手，逐步上手

入手项目的初期不要好高骛远，我们从解小的BUG开始熟悉怎么正确的提交第一个PR，在这个过程中我们可以学习项目的规范，正确的写单元测试，然后解BUG的过程中我们不要看哪里的代码就只是哪里的代码，我们还需要关注模块的边界，了解整个模块都有一些什么功能。很多的BUG往往不是主要功能流程中的问题，在处理这些小的BUG的时候正是我们去了解其它非主要流程功能的好机会。

6. 新功能与重构

当我们对项目有一定的了解后，就可以做一些新功能了，然后在规划新功能时，往往我们需要对涉及到已有的代码做一些重构，我们需要把握代码重构的一个度，一定是有限处理对我们写新功能有阻碍的代码，然后需要考虑功能的后续迭代与未来的演进来重构。渐进式的重构，不要上来就搞大的，我相信很多程序员都希望能把代码写的跟符合自己的审美，但是初期还是要以功能为主，再实现功能的同时小步渐进式的重构。重构有很多技巧，我们可以把我们改不动的代码做隔离，先保证能跑起来，然后再完善。

总结

初入一个项目，我们可能会遇到很多很多问题，但是没有关系的，我们需要做的是把这些疑问都记录下来，然后带着疑问慢慢去熟悉，熟悉一个项目也需要一个过程，不要着急，1个星期不行，就1个月，遇到困难就及时寻求帮助。前人种树，后人乘凉。如果前人没能帮你种好树，那我们就把我们熟悉项目的过程整理成文档，留给后人，这样后人就可以少走很多弯路。