08 Django项目开发规范

优质

小牛编辑

127浏览

2023-12-01

这里会简单介绍下基于 Django 框架开发 Web 项目中要遵守的一些基本开发规范。

1. Django 开发规范

对于 Django 的开发规范，我个人的总结如下：

正式开始基于 Django 的 Web 服务项目之前，需要完成相应的需求和接口设计，而不要冒冒然直接开写；
工程需要有完整的文档介绍、服务部署脚本（start、stop）等等，让这个项目至少看起来高大上和完整；
完善的版本迭代机制，每个版本的需求说明、bug 更新文档以及相应的版本号。

这些初始的规范在其他 Web 项目开发中也是合适的，最重要也是最难的一件事情就是坚持做好上面这些，同时坚持良好的代码规范。

2. Django 文件规范

首先针对 Django 的文件规范，其实和其他 Web 开发差不多，需要做到如下几点：

项目中目录命名尽量有含义。比如常用的 utils 目录下，一般放一些自己写的常用函数或者通用类；
项目中新增加的代码文件命名尽量准确并体现里面代码功能，比如新增一个处理路径相关的代码，文件可以命名为 path.py；
Django 中给我们新建的 models.py，views.py，我们要尽量按照它定义的功能编写代码，比如 models.py 是用来定义所在应用的数据库模型的，views.py 是用来编写本应用的视图函数。我们在该应用中添加的模块代码也要命名清晰，比如后面我们在每个应用中会添加 urls.py 文件，该文件中定义了本应用的所有 URL 和对应的视图；

来看看 Django 框架的源代码示意图，如下：

图片描述

django 源码图

从这里我们是不是能够感受到一个流行框架的项目是不是具备我们上面描述的规范呢？在 Django 的框架源码中，每一个模块的代码都在对应的目录中，每个目录下的代码文件命名十分清晰明了，比如 request.py 和 response.py 直接从文件名就能看出这个文件的功能。

3. Django 接口规范

对于 Django 的 URL 接口规范，遵循如下几点规则：

开发之前，先要详细设计项目的 API 接口，包括输入参数以及响应数据的格式，最好能形成相关的接口文档；
URL 接口要按照应用划分，每个 App 目录里面要有自己的 urls.py 文件。里面是本应用中的所有 url 和视图的映射关系。总的 url 入口在 settings.py 文件中配置，默认是和 settings.py 文件同目录下的 urls.py；
对于 URL 接口本身，倾向于使用 Restful 风格的 API 接口设计，比如接口：
- /manage/user：对应的 GET、POST、PUT 和 Delete 请求，我们往往会对应着用户模型 user 的增删改查操作
这样的规范只是一种广泛使用的 API 接口设计风格，并不是必须的。因此在 Django 中的各种 View 类来辅助我们设计这样的 API 接口。
在项目中实现 Django 的 Web API 接口时，往往是使用 DFR （Django Rest Framework）来辅助构建项目的 API 接口。DRF 在 Django 的基础上迅速实现 API ，并且自身还带有 Web 的测试页面，可以方便的测试自己的 API 接口；

最后就是关于公司内部接口设计人的喜好了，比如有人喜欢讲第一版本和第二版本接口设计用这样的 URL区分：

https://example.com/api/v1/book/1  -> v1 版本接口
https://example.com/api/v2/book/1  -> v2 版本接口

还有设计响应数据的格式，也要简单明了。比如可以简单使用如下的 JSON 数据表示响应结果：

{
    "code": 200,                # 响应码
    "content": [] or {} or "",  # 返回数据内容，可以是[]、{} or str等
    "err_msg": ""               # 错误信息
}

4. Django 代码规范

最后的是 Django 代码规范，也是 Python 代码的规范。总结个人在看源码以及在写代码之间尽量避免的一些问题：

不要重复代码！不要重复代码！不要重复代码！重要的事情说三遍。在 Python 开发中，我们尽量不要写重复代码，将同一个功能的代码尽可能封装成函数以供调用；

python 代码中变量、函数、类的命名，尽量有含义，比如下面定义的 Connection 类：

class Connection(BaseConnection):
    def __init__(self, host, port, user, passwd):
        ...
    
    # 远程执行shell命令
    def run_command(cmd):
        ...
        
    # 上传文件到远端服务器
    def upload_file(source_src, dest_src, mode):
        ...
        
    # 从远端服务器上下载文件    
    def download_file(remote_src, dest_src, mode):
        ...
        
    ...

可以看到，这里从类名到参数，到函数名都能从名称上推测出其作用。

不要盲目在一个函数中堆砌代码。一个函数内的代码尽量控制在如 50 行内，每行的代码的长度也不要过长，容易引起视觉反感；
如果有能力，需要多学习一些设计模式相关知识，还有 Python 的各种高级用法。有时候不是为了酷炫，而是这样使用能做到非常好的简化代码和封装代码；
此外，尽量使用一些做的比较好的第三方插件，比如 DRF 帮助我们快速实现 Web API 接口，同时还提供了认证相关功能，可以让我们简化开发难度，而且提供良好的代码风格。在一些情况下，尽量避免自己重复造轮子，而且造的是差轮子；
编写函数测试用例。这个是很多开发工程师不愿意做的但是又十分重要的一点。对于一些重要函数，我们一定要记得给这个函数设计一个测试用例，避免后续有人接收是改动该函数能及时发现异常

以上是我在工作中的一些体会，主要是在开发中碰到的一些常见的规范问题。有些公司的代码规范会详细到如何定义好的变量名、对注释的限制等等。养成良好的 Python 代码规范是项目中的一个重要环节。一个非常好的途径就是去学习 Python 项目的相关源码，这里推荐的有： Flask、Django、Ansible 等流行的开源项目，从中可以学到不少设计模式以及 Python 中的高级用法。

5. 小结

本小节中，我从自己的角度总结了一些 Django 项目开发过程中要注意的一些事项，当然这里也只是一些个人见解。读者可以参考部分觉的有益的建议，也可以使用符合本公司项目情况的相关规范。规范是为了让更多的开发人员能很好的了解和完善项目。如果在进行项目开发前，没有相关的规范，随着时间的推移，不同的开发人员有着各自的开发风格，最后导致的结果就是大部分项目的风格混乱，结构不清，代码也是惨不忍睹，最后被后续接手的人疯狂吐槽。当然，有好的规范不一定能做成好的项目，但是没有好的规范的项目，往往是做不成功的。