[Python学习日记-55] 软件开发目录设计规范

news2024/11/26 4:25:54

[Python学习日记-55] 软件开发目录设计规范

简介

为什么要设计好目录结构?

目录组织方式

关于 README 的内容

关于 setup.py 和 requirements.txt

关于配置文件的使用方法

简介

        我们在浏览一些开源项目或者是一些安装后的软件的时候会发现,不同的两个项目之间居然会有一些目录的名称居然是一样的,而且放置的程序代码的功能也是相近的。其实这并不是巧合,这就是一个行业的惯例,正规程序员都会使用的一个目录结构,下面我们一起来学习一下到底如何设计好自己项目的目录结构吧。

为什么要设计好目录结构?

        “设计项目目录结构”,就和“代码编码风格”一样,属于个人风格问题,对于这种风格上的规范,一直都存在两种态度:

  1. 一类人认为,这种个人风格问题“无关紧要”。理由是能让程序正常运行就好了,风格问题根本不是问题
  2. 另一类人认为,规范化能更好的控制程序结构,让程序具有更高的可读性

        你是倾向于哪一类呢?而我是更倾向于后者的,试想一下,你的同学或者同事他要离开项目了,然后你是他的下一任接手人,当你看到第一类的项目时会是什么感觉,及时项目的实现逻辑并不复杂,但由于可读性差的原因却耗费了接手人非常长的时间去理解原代码想表达的意思。所以说正规项目和大厂的项目通常都是有项目可读性、可维护性的要求的,而且这个要求只会高不会低。我们在这里所提到的“项目目录结构”其实也是属于“可读性和可维护性”的范畴,我们设计一个层次清晰的目录结构,就是为了达到以下两点:

  1. 可读性高:不熟悉这个项目代码的人,一眼就能看懂目录结构,知道程序启动脚本是哪个,测试目录在哪儿,配置文件在哪里等等。从而可以非常快速的了解这个项目
  2. 可维护性高:定义好组织规则后,维护者就能很明确地知道,新增的哪个文件和代码应该放在什么目录之下。这个好处是,随着时间的推移,代码和配置的规模增加,项目结构不会混乱,仍然能够组织良好

        总的来说,保持一个层次清晰的目录结构是有必要的,更何况组织一个良好的工程目录,其实是一件很简单的事情。

目录组织方式

        关于如何组织一个较好的 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 的内容

        该文件我认为是每个项目都应该有的一个文件,目的是能简要描述该项目的信息,让读者快速了解这个项目。它需要说明以下几个事项:

  1. 软件定位,软件的基本功能
  2. 运行代码的方法,例如安装环境、启动命令等
  3. 简要的使用说明
  4. 代码目录结构说明,更详细点可以说明软件的基本原理
  5. 常见问题说明

关于 setup.py 和 requirements.txt

一、setup.py

        一般来说,用 setup.py 来管理代码的打包、安装、部看问题。业界标准的写法是用 Python 流行的打包工具 setuptools 来管理这些事情。这种方式普遍应用于开源项目中。不过这里的核心思想不是用标准化的工具来解决这些问题,而是说一个项目一定要有一个安装部暑工具,能快速便捷的在一台新机器上将环境装好、代码部暑好和将程序运行起来。

        假设你写了一个项目,安装环境、部署代码、运行程序这个过程全是手动完成,很容易遇到过以下问题: 

  1. 安装环境时经常忘了最近又添加了一个新的 Python 包,结果一到线上运行,程序就出错了
  2. Python 包的版本依赖问题,有时候我们程序中使用的是一个特定版本的 Python 包,但是官方的已经是最新的版本了,通过手动安装就可能装错了版本,导致程序出错
  3. 如果依赖的包很多的话,一个一个安装这些依赖的包会非常消耗时间
  4. 小白开始写项目的时候,将程序跑起来非常麻烦,因为可能经常忘了要怎么安装各种依赖包

        而 setup.py 就可以将这些事情自动化起来,提高效率、减少出错的概率。“复杂的东西自动化,能自动化的东西一定要自动化。”是一个非常好的习惯。setuptools 的文档比较庞大,刚接触的话,可能不太好找到切入点。学习技术的方式就是看他人是怎么用的,可以参考一下 Python 的一个 Web 框架,fask 是如何写的 setup.py
        当然,简单点自己写个安装脚本(deploy.sh)来替代 setup.py 也未尝不可。

二、requirements.txt

        这个文件存在的目的是:

  1. 方便开发者维护软件的包依赖。将开发过程中新增的包添加进这个列表中,避免在 setup·py 安装依赖时漏掉某些软件包
  2. 方便读者明确项目使用了哪些 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/ 目录下。

        很多项目对配置文件(把配置文件放在源码目录下)的使用做法是:

  1. 配置文件写在一个或多个 Python 文件中
  2. 项目中哪个模块用到这个配置文件就直接通过 import conf 这种形式来在代码中使用配置。

        这种做法不敢苟同,这是因为:

  1. 这让单元测试变得困难(因为模块内部依赖了外部配置)
  2. 另一方面配置文件作为用户控制程序的接口,应当可以由用户自由指定该文件的路径
  3. 程序组件可复用性太差,因为这种贯穿所有模块的代码硬编码方式,使得大部分模块都依赖 conf.py 这个文件

        所以,我认为配置的使用更好的方式是:

  1. 模块的配置都是可以灵活配置的,不受外部配置文件的影响
  2. 程序的配置也是可以灵活控制的

        能够佐证这个思想的是,用过 nginx 和 mysql 的都知道,nginx 和 mysql 这些程序都可以自由的指定用户配置的。所以不应当在代码中直接 import conf 来使用配置文件。上面目录结构中的 conf.py,是给出的一个配置样例,不是在写死在程序中直接引用的配置文件。可以通过给 main.py 启动参数指定配置路径的方式来让程序读取配置内容。当然,这里的 conf.py 你可以换个类似的名字,例如 settings.py 之类的。或者你也可以使用其他格式的内容来编写配置文件,例如 settings.yaml 之类的。

本文来自互联网用户投稿,该文观点仅代表作者本人,不代表本站立场。本站仅提供信息存储空间服务,不拥有所有权,不承担相关法律责任。如若转载,请注明出处:http://www.coloradmin.cn/o/2232168.html

如若内容造成侵权/违法违规/事实不符,请联系多彩编程网进行投诉反馈,一经查实,立即删除!

相关文章

18.农产品销售系统(基于springboot和vue的Java项目)

目录 1.系统的受众说明 2.开发环境与技术 2.1 Java语言 2.2 MYSQL数据库 2.3 IDEA开发工具 2.4 Spring Boot框架 3.系统分析 3.1 可行性分析 3.1.1 技术可行性 3.1.2 经济可行性 3.1.3 操作可行性 3.2 系统流程 3.2.1 操作流程 3.2.2 登录流程 3.2.3 删除信…

嵌入式常用功能之通讯协议1--IIC

嵌入式常用功能之通讯协议1--串口 嵌入式常用功能之通讯协议1--IIC(本文) 嵌入式常用功能之通讯协议1--SPI 一、IIC总线协议介绍 Inter-Integrated Circuit(集成电路总线),是由 Philips 半导体公司(现在的 NXP 半导体…

一位纯理科生,跨界自学中医,自行组方治好胃病、颈椎病与高血脂症,并在最权威的中国中医药出版社出版壹本专业中医图书!

这是一位铁杆中医迷, 也是《神农本草经——精注易读本》的作者。 希望更多的人能够受到启发,感受中医之神奇,敢于跨界,爱好中医,学习中医! 一个病人以自己的切身感受与诊断,并使之汤药治愈疾病&…

java项目之个人博客系统的设计与实现(springboot)

风定落花生,歌声逐流水,大家好我是风歌,混迹在java圈的辛苦码农。今天要和大家聊的是一款基于springboot的闲一品交易平台。项目源码以及部署相关请联系风歌,文末附上联系信息 。 项目简介: springboot个人博客系统的…

使用 Sortable.js 库 实现 Vue3 elementPlus 的 el-table 拖拽排序

文章目录 实现效果Sortable.js介绍下载依赖添加类名导入sortablejs初始化拖拽实例拖拽完成后的处理总结 在开发过程中,我们经常需要处理表格数据,并为用户提供便捷的排序方式。特别是在需要管理长列表、分类数据或动态内容时,拖拽排序功能显得…

使用Kafka构建大规模消息传递系统

💓 博客主页:瑕疵的CSDN主页 📝 Gitee主页:瑕疵的gitee主页 ⏩ 文章专栏:《热点资讯》 使用Kafka构建大规模消息传递系统 引言 Kafka 简介 安装 Kafka 创建主题 生产者 消费者 高级特性 分区 持久化 消费者组 消息确认…

队列(Queue)的介绍与实现

文章目录 队列队列的概念及结构 队列的实现初始化队列销毁队列队尾入队列队头出队列获取队列头部元素检测队列是否为空获取队列中有效元素个数 队列 队列的概念及结构 队列:只允许在一端进行插入数据操作,在另一端进行删除数据操作的特殊线性表。队列遵…

【大模型之Graph RAG系列之二】对比传统RAG技术中使用的向量搜索技术,知识图谱有哪些优缺点?

向量搜索和知识图谱是两项用于改善搜索体验的重要技术。结合这两种技术形成的Graph RAG可以进一步提高搜索的准确性和上下文相关性。本文将深入对比向量搜索和知识图谱,让读者快速了解这两种技术的原理及优缺点,以便于将来的技术决策。 向量搜索 向量搜…

电赛入门之软件stm32keil+cubemx

hal库可以帮我们一键生成许多基本配置,就不需要自己写了,用多了hal库就会发现原来用基本库的时候都过的什么苦日子(笑 下面我们以f103c8t6,也就是经典的最小核心板来演示 一、配置工程 首先来新建一个工程 这里我们配置rcc和sys&…

从“技术深耕”到“品牌绽放”,解码遨游通讯的高成长路径!

在粤港澳大湾区这片充满活力的土地上,科技创新正以前所未有的速度推动着各行各业的发展。在这样一个充满机遇与挑战的环境中,遨游通讯以其在危险作业场景和应急救援场景中提供的定制化智能终端解决方案,脱颖而出,成为危急特赛道的…

golang通用后台管理系统02(RSA加密解密,登录密码加密解密)

参考:https://blog.csdn.net/lady_killer9/article/details/118026802 1.加密解密工具类PasswordUtil.go package utilimport ("crypto/rand""crypto/rsa""crypto/x509""encoding/pem""fmt""log"&qu…

【HarmonyOS NEXT】在 HarmonyOS NEXT 中实现优雅的加载动画

【HarmonyOS NEXT】在 HarmonyOS NEXT 中实现优雅的加载动画 在移动应用开发中,加载动画是提升用户体验的重要工具。在应用程序处理数据或加载页面时,为用户提供视觉反馈尤为关键。在这篇博客中,我们将探讨如何在 HarmonyOS NEXT 中使用 Sta…

群控系统服务端开发模式-应用开发-菜单功能开发

为什么优先开发菜单,而不是优先开发管理员?查看一下程序草图就明白,还有一个重点就是,管理员需要添加图片,而我还没有封装上传工具及上传目标。 一、添加路由 在根目录下route文件夹下的app.php文件里面,添…

服务器新建用户

文章目录 前言一、步骤二、问题三、赋予管理员权限总结 前言 环境: 一、步骤 创建用户需要管理员权限sudo sudo useradd tang为用户设置密码 sudo passwd tang设置密码后,可以尝试使用 su 切换到 tang 用户,确保该用户可以正常使用&#…

AI产品独立开发变现实战营

亮点: 1、三大真实商业项目,商业盈利、AI产品开发综合能力提升 2、掌握一人公司、副业产品设计-开发-运营-盈利落地全流程 3、大牛私藏AI盈利工具倾囊相授 4、借势增加睡后收入,从容应对裁员大环境与年龄危机 大纲: 第1章 独立…

Spring Boot技术:校园社团信息管理的高效路径

5系统详细实现 5.1 管理员模块的实现 5.1.1 学生管理 校园社团信息管理系统的系统管理员可以管理学生,可以对学生信息修改删除以及查询操作。具体界面的展示如图5.1所示。 图5.1 学生信息管理界面 5.1.2 社长管理 系统管理员可以查看对社长信息进行修改&#xff0…

Python小游戏20——超级玛丽

首先,你需要确保你的Python环境中安装了pygame库。如果还没有安装,可以使用以下命令进行安装: bash pip install pygame 运行效果展示 代码展示 python import pygame import sys # 初始化pygame pygame.init() # 设置屏幕尺寸 screen_width …

我也谈AI

“随着人工智能技术的不断发展,我们已经看到了它在各行业带来的巨大变革。在医疗行业中,人工智能技术正在被应用于病例诊断、药物研发等方面,为医学研究和临床治疗提供了新的思路和方法;在企业中,人工智能技术可以通过…

【论文复现】语言模型中的多模态链式推理

📕作者简介:热爱跑步的恒川,致力于C/C、Java、Python等多编程语言,热爱跑步,喜爱音乐、摄影的一位博主。 📗本文收录于论文复现系列,大家有兴趣的可以看一看 📘相关专栏C语言初阶、C…

ios Framework版本号的问题。

自己创建的framework和普通的app的版本号设置的地方是有所有不同的。 framework 的版本号是在 TARGETS -> Build Settings -> current Project Version 这个地方设置的, 在创建framework的时候xcode 会自动创建一个framework.h的文件名,framewo…