[Python学习日记-54] 软件开发目录设计规范
[Python学习日记-54] 软件开发目录设计规范
简介
为什么要设计好目录结构？
目录组织方式
关于 README 的内容
关于 setup.py 和 requirements.txt
关于配置文件的使用方法
简介
我们在浏览一些开源项目或者是一些安装后的软件的时候会发现，不同的两个项目之间居然会有一些目录的名称居然是一样的，而且放置的程序代码的功能也是相近的。其实这并不是巧合，这就是一个行业的惯例，正规程序员都会使用的一个目录结构，下面我们一起来学习一下到底如何设计好自己项目的目录结构吧。
为什么要设计好目录结构？
“设计项目目录结构”，就和“代码编码风格”一样，属于个人风格问题，对于这种风格上的规范，一直都存在两种态度：
- 一类人认为，这种个人风格问题“无关紧要”。理由是能让程序正常运行就好了，风格问题根本不是问题
- 另一类人认为，规范化能更好的控制程序结构，让程序具有更高的可读性
你是倾向于哪一类呢？而我是更倾向于后者的，试想一下，你的同学或者同事他要离开项目了，然后你是他的下一任接手人，当你看到第一类的项目时会是什么感觉，及时项目的实现逻辑并不复杂，但由于可读性差的原因却耗费了接手人非常长的时间去理解原代码想表达的意思。所以说正规项目和大厂的项目通常都是有项目可读性、可维护性的要求的，而且这个要求只会高不会低。我们在这里所提到的“项目目录结构”其实也是属于“可读性和可维护性”的范畴，我们设计一个层次清晰的目录结构，就是为了达到以下两点：
- 可读性高：不熟悉这个项目代码的人，一眼就能看懂目录结构，知道程序启动脚本是哪个，测试目录在哪儿，配置文件在哪里等等。从而可以非常快速的了解这个项目
- 可维护性高：定义好组织规则后，维护者就能很明确地知道，新增的哪个文件和代码应该放在什么目录之下。这个好处是，随着时间的推移，代码和配置的规模增加，项目结构不会混乱，仍然能够组织良好
总的来说，保持一个层次清晰的目录结构是有必要的，更何况组织一个良好的工程目录，其实是一件很简单的事情。
目录组织方式
关于如何组织一个较好的 Python 工程目录结构，已经有一些得到了共识的目录结构。在各大开发者社区论坛当中都能可能到大家对 Python 目录结构的讨论。下面直接来说说我认为比较好的目录结构吧。
假设你的项目名为 foo，我比较建议的最方便快捷目录结构这样就足够了：
Foo/
| -- bin/
| | -- foo
|
| -- foo/
| | -- tests/
| | | -- __init__.py
| | | -- test_main.py
| |
| | -- __init__.py
| | -- main.py
|
| -- docs/
| | -- abc.rst
|
| -- confs/
| | -- conf.py
|
| -- setup.py
| -- requirements.txt
| -- README
目录解析：
- bin/：存放项目的一些可执行文件，当然你可以起名 script/ 之类的也行
- foo/：存放项目的所有源代码
（1）源代码中的所有模块、包都应该放在此目录。不要置于顶层目录
（2）其子目录 tests/ 存放单元测试代码
（3）程序的入口最好命名为 main.py - docs/：存放一些文档
- confs/：存放一些项目的配置文件，当项目比较小的时候该目录可以不建，可以把配置文件与 docs/ 放在一起
- setup.py：安装、部署、打包的脚本
- requirements.txt：存放软件依赖的外部 Python 包列表
- README：项目说明文件
除此之外，有一些方案给出了更加多的内容。例如 LICENSE.txt、ChangeLog.txt 文件等，但没在这里列出，因为这些东西主要是项目开源的时候需要用到。如果你想写一个开源软件，目录该如何组织，可以参考这两篇文章：(1)和(2)。
关于 README 的内容
该文件我认为是每个项目都应该有的一个文件，目的是能简要描述该项目的信息，让读者快速了解这个项目。它需要说明以下几个事项：
- 软件定位，软件的基本功能
- 运行代码的方法，例如安装环境、启动命令等
- 简要的使用说明
- 代码目录结构说明，更详细点可以说明软件的基本原理
- 常见问题说明
关于 setup.py 和 requirements.txt
一、setup.py
一般来说，用 setup.py 来管理代码的打包、安装、部看问题。业界标准的写法是用 Python 流行的打包工具 setuptools 来管理这些事情。这种方式普遍应用于开源项目中。不过这里的核心思想不是用标准化的工具来解决这些问题，而是说一个项目一定要有一个安装部暑工具，能快速便捷的在一台新机器上将环境装好、代码部暑好和将程序运行起来。
假设你写了一个项目，安装环境、部署代码、运行程序这个过程全是手动完成，很容易遇到过以下问题：
- 安装环境时经常忘了最近又添加了一个新的 Python 包，结果一到线上运行，程序就出错了
- Python 包的版本依赖问题，有时候我们程序中使用的是一个特定版本的 Python 包，但是官方的已经是最新的版本了，通过手动安装就可能装错了版本，导致程序出错
- 如果依赖的包很多的话，一个一个安装这些依赖的包会非常消耗时间
- 小白开始写项目的时候，将程序跑起来非常麻烦，因为可能经常忘了要怎么安装各种依赖包
而 setup.py 就可以将这些事情自动化起来，提高效率、减少出错的概率。“复杂的东西自动化，能自动化的东西一定要自动化。”是一个非常好的习惯。setuptools 的文档比较庞大，刚接触的话，可能不太好找到切入点。学习技术的方式就是看他人是怎么用的，可以参考一下 Python 的一个 Web 框架，fask 是如何写的 setup.py
当然，简单点自己写个安装脚本（deploy.sh）来替代 setup.py 也未尝不可。
二、requirements.txt
这个文件存在的目的是：
- 方便开发者维护软件的包依赖。将开发过程中新增的包添加进这个列表中，避免在 setup·py 安装依赖时漏掉某些软件包
- 方便读者明确项目使用了哪些 Python 包
这个文件的格式是每一行包含一个包依赖的说明，通常是 flask>=0.10 这种格式，要求是这个格式能被 pip 识别，这样就可以简单的通过 pip install -r requirements.txt 来把所有 Python 包依赖都装好了，下面我们来简单演示一下 requirements.txt 文件的制作
假设我们开发的项目会用到我们所有安装的 Python 包，这样我们可以先用以下命令来查看系统上装了什么 Python 包，并导出为 requirement.txt 文件
pip list # 查看当前python已安装的包
pip freeze > requirements.txt # 如果这些安装包都是项目在用的可以用这条命令生成 requirements.txt 文件
如果导出的数据包并不完全是项目会用到的，我们可以对文件进行修改。
关于配置文件的使用方法
注意：在上面的目录结构中，没有将 conf.py 放在源码目录下，而是放在 confs/ 目录下。
很多项目对配置文件（把配置文件放在源码目录下）的使用做法是：
- 配置文件写在一个或多个 Python 文件中
- 项目中哪个模块用到这个配置文件就直接通过 import conf 这种形式来在代码中使用配置。
这种做法不敢苟同，这是因为：
- 这让单元测试变得困难（因为模块内部依赖了外部配置）
- 另一方面配置文件作为用户控制程序的接口，应当可以由用户自由指定该文件的路径
- 程序组件可复用性太差，因为这种贯穿所有模块的代码硬编码方式，使得大部分模块都依赖 conf.py 这个文件
所以，我认为配置的使用更好的方式是：
- 模块的配置都是可以灵活配置的，不受外部配置文件的影响
- 程序的配置也是可以灵活控制的
能够佐证这个思想的是，用过 nginx 和 mysql 的都知道，nginx 和 mysql 这些程序都可以自由的指定用户配置的。所以不应当在代码中直接 import conf 来使用配置文件。上面目录结构中的 conf.py，是给出的一个配置样例，不是在写死在程序中直接引用的配置文件。可以通过给 main.py 启动参数指定配置路径的方式来让程序读取配置内容。当然，这里的 conf.py 你可以换个类似的名字，例如 settings.py 之类的。或者你也可以使用其他格式的内容来编写配置文件，例如 settings.yaml 之类的。